Configurando webhooks

POST /webhook · GET /webhook · DELETE /webhook/{id}

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)
• Filtro por tipo — você assina só os eventos que interessam para sua integração

2. Pré-requisitos

• Endpoint HTTPS público com certificado válido (TLS 1.2+). HTTP e self-signed são rejeitados.
• Capacidade de responder em até 10 segundos — após esse tempo a IORQ considera falha e retenta.
• Token Bearer JWT válido para chamar POST /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 /webhook

POST /webhook · application/json

Campos do payload

Exemplo:

curl -X POST 'https://hs-api.iorq.com.br/webhook' \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.meudominio.com/iorq-webhooks",
    "events": ["loan_received", "loan_approved", "loan_rejected", "disbursement_completed", "installment_settled"],
    "description": "Produção · principal"
  }'

Resposta:

{
  "webhook_id": "wh_2A8f1b3c4d5e",
  "url": "https://api.meudominio.com/iorq-webhooks",
  "events": ["loan_received", "loan_approved", "loan_rejected", "disbursement_completed", "installment_settled"],
  "signing_secret": "whsec_K8nP3qR7sT2vW9xY1zA4bC6dE0fG5hJ",
  "status": "active",
  "created_at": "2026-05-13T12:00:00Z"
}

🚧

Guarde o signing_secret imediatamente

Ele não é retornado em nenhuma chamada subsequente. Em caso de perda, gere um novo via POST /webhook/{id}/rotate-secret — o antigo deixa de validar a partir desse momento.

4. Formato dos eventos recebidos

Todo evento é enviado como POST JSON para a URL registrada, com headers específicos da IORQ:

Headers

Body

{
  "event": "loan_approved",
  "event_id": "evt_9c4a8b2d1e5f",
  "originator_proposal_code": "OP-001",
  "fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36",
  "timestamp": "2026-05-13T12:02:34Z",
  "data": {
    "/* payload específico do evento */": null
  }
}

O campo data varia por evento. Veja o Catálogo de eventos para os schemas específicos.

5. Validar o primeiro evento

Após registrar a URL, a IORQ envia um evento webhook.ping em sandbox para você confirmar que a configuração funciona:

{
  "event": "webhook.ping",
  "event_id": "evt_test_abc123",
  "timestamp": "2026-05-13T12:00:05Z",
  "data": { "message": "Webhook configured successfully" }
}

Para validar a assinatura HMAC em Python:

import hmac, hashlib

def verify(payload_bytes, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Implementações em Node.js, Go e Java em Configuração e segurança.

6. Gerenciar webhooks existentes

7. Próximos passos