Visão geral

Webhooks avisam os seus sistemas, em tempo quase real, sobre fatos de negócio do Dunning: cobrança paga, acordo aceito, disputa aberta, notificação entregue. Em vez de consultar a API de tempos em tempos, você cadastra um endpoint HTTPS e recebe cada evento como um POST JSON.

Como funciona

1. Um fato acontece (ex.: pagamento identificado).
2. O evento é persistido de forma imutável — nada é fire-and-forget.
3. Para cada endpoint assinante, o sistema agenda uma entrega com assinatura HMAC e a envia com retry automático; cada tentativa fica registrada com request e response capturados.

Cadastrando um endpoint

Na tela Webhooks do dashboard (ou via POST /api/v1/webhook-endpoints), informe:

• URL: obrigatoriamente https://. URLs que apontam para redes internas são rejeitadas no cadastro (INVALID_WEBHOOK_URL, proteção anti-SSRF).
• Descrição (opcional): para que serve esse endpoint.
• Eventos: selecione no catálogo, agrupado por categoria, com "selecionar todos" por grupo. Lista vazia assina todos os eventos, inclusive os que forem criados no futuro (a listagem mostra o badge "Todos os eventos").
• Autenticação (opcional): credenciais que o Dunning apresenta ao seu endpoint (Basic, Bearer ou header custom), além da assinatura HMAC que vai sempre. Detalhes em Segurança.

Ao criar, o secret do endpoint (prefixo whsec_) é exibido uma única vez. Ele assina cada entrega e pode ser rotacionado a qualquer momento.

O que chega no seu endpoint

Cada entrega é um POST com o payload:

{
  "event": "charge.paid",
  "timestamp": "2026-07-23T12:00:00.000Z",
  "organizationId": "3f8a...",
  "data": { "id": "...", "status": "paid", "...": "o recurso serializado" }
}

E os headers:

Content-Type: application/json
User-Agent: Kobana-Dunning-Webhooks/1.0
X-Webhook-Event: charge.paid
X-Webhook-Event-Id: 3d1f0c9a-…      (UUID do evento — o mesmo em todos os retries)
X-Webhook-Delivery-Id: 9b2e4a10-…   (UUID da entrega — único por evento × endpoint)
X-Webhook-Attempt: 1                (número da tentativa)
X-Webhook-Timestamp: 2026-07-23T12:00:00.000Z
X-Webhook-Signature: t=<unix>,v1=<hmac-sha256 de "t.body" com o secret>

Responda 2xx para confirmar o recebimento. Qualquer outra resposta (incluindo redirects, que não são seguidos) conta como falha e entra no ciclo de retry.

Testando o endpoint

Depois de cadastrar, dispare um evento de teste com POST /api/v1/webhook-endpoints/{id}/test: um evento webhook.test percorre o pipeline real (fila, assinatura, captura, retry) até o seu consumidor — sem esperar um evento de negócio acontecer.

Boas práticas

• Responda rápido e processe depois: enfileire o payload e devolva 200 imediatamente (o timeout de entrega é de 10 segundos).
• Trate como pelo menos-uma-vez: retries podem entregar o mesmo evento mais de uma vez; deduplique pelo X-Webhook-Event-Id (estável entre tentativas).
• Verifique a assinatura sempre, inclusive a janela de tolerância do timestamp (como fazer).
• Monitore a tela de entregas: falhas e esgotamentos ficam visíveis por endpoint, com re-envio manual.

Nesta seção

• Eventos — o catálogo completo com payload de exemplo, recurso por recurso.
• Segurança — assinatura HMAC, verificação e autenticação do request.
• Entregas e retry — captura, backoff, DLQ e re-envio manual.