Configurando webhooks

POST /api/webhook · GET /api/webhook · PATCH /api/webhook/{id}

Os endpoints de webhook ficam no serviço webhook-sender-manager (host próprio, ex.: https://webhook-sender-manager-production.iorq.com.br/api) e exigem o header iorq-fund-id — o UUID do fundo recebido por e-mail — além do Authorization.

1. Por que webhooks

O ciclo de uma operação envolve múltiplos atores fora do controle do integrador: validação de elegibilidade, geração de termo na administradora, coleta de assinaturas, desembolso bancário. Em vez de você ficar pollando estado, a IORQ te avisa quando algo muda.

• Latência baixa — eventos são entregues em segundos após a mudança
• Reentrega garantida — se sua URL falha, a IORQ retenta (ver Idempotência e reentrega)
• Um tipo de mensagem — hoje a IORQ envia o message_type LOAN_UPDATE; o que mudou vem no data.status do payload

2. Pré-requisitos

• Endpoint HTTPS público com certificado válido (TLS 1.2+). HTTP e self-signed são rejeitados.
• Capacidade de responder rápido — após o timeout a IORQ considera falha e retenta.
• Token Bearer JWT válido + header iorq-fund-id para chamar POST /api/webhook (ver Autenticação).

📘

Recomendação

Antes de processar o evento, enfileire-o (SQS, RabbitMQ, etc.) e responda 200 ao webhook. Processamento síncrono dentro do handler é frágil — uma lentidão downstream estoura o timeout de 10s.

3. Registrar uma URL de webhook

3.1 POST /api/webhook

POST /api/webhook · application/json

Campos do payload

O fundo é definido pelo header iorq-fund-id da requisição (UUID do e-mail de credenciais), não por um campo no corpo.

Exemplo:

curl -X POST 'https://webhook-sender-manager-production.iorq.com.br/api/webhook' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'iorq-fund-id: 374485cf-f6df-467c-b91d-9f14082c6f36' \
  -H 'Content-Type: application/json' \
  -d '{
    "message_type": "LOAN_UPDATE",
    "webhook_url": "https://api.meudominio.com/iorq-webhooks",
    "headers": { "X-My-Auth": "meu-token" }
  }'

Resposta:

{
  "webhook_id": "...",
  "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
  "user_id": "...",
  "message_type": "LOAN_UPDATE",
  "webhook_url": "https://api.meudominio.com/iorq-webhooks",
  "status": "ACTIVE",
  "headers": { "X-My-Auth": "meu-token" },
  "max_attempts": 7,
  "created_at": "2026-05-13T12:00:00Z",
  "updated_at": "2026-05-13T12:00:00Z",
  "signing_secret": "whsec_K8nP3qR7sT2vW9xY1zA4bC6dE0fG5hJ"
}

🚧

Guarde o signing_secret imediatamente

Ele aparece apenas nesta resposta — GET, PATCH e listagem não o retornam. É com ele que você valida a assinatura X-IORQ-Signature de cada entrega. Ver Configuração e segurança.

4. Formato dos eventos recebidos

Cada evento é enviado como POST JSON para a webhook_url, assinado com HMAC-SHA256:

Headers

Body

{
  "event": "update",
  "data": {
    "entity_id": "OP-001",
    "status": "approved",
    "reason": null,
    "nosso_numero": null,
    "installment_code": null,
    "entity_type": "ccb"
  },
  "iorq_fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36"
}

O discriminador do que mudou é data.status. Veja o Catálogo de eventos para todos os valores possíveis.

O iorq_fund_id no topo do corpo é o UUID do fundo do evento — o mesmo informado no header iorq-fund-id ao registrar o webhook. Ele existe para quem integra mais de um fundo rotear pelo próprio corpo, e é assinado junto com o resto (o HMAC cobre o corpo inteiro, iorq_fund_id incluído). Se o seu parser rejeita campos não previstos, libere iorq_fund_id.

5. Validar a configuração

Use o iorq-fund-id e o webhook_id retornado para conferir o registro:

curl 'https://webhook-sender-manager-production.iorq.com.br/api/webhook' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'iorq-fund-id: 374485cf-f6df-467c-b91d-9f14082c6f36'

Para autenticar as entregas no seu endpoint, valide a assinatura HMAC com o signing_secret (comparação em tempo constante):

import hmac, hashlib, time

def verify(payload_bytes, signature_header, secret, tolerance=300):
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    ts, sig = parts["t"], parts["v1"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    signed = f"{ts}.{payload_bytes.decode()}"
    expected = hmac.new(secret.encode(), signed.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Implementação em Node.js e detalhes de replay em Configuração e segurança.

6. Gerenciar webhooks existentes

7. Próximos passos