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 /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",
  "organization_id": "3f8a...",
  "workspace_id": "5e8d...",
  "data": { "id": "...", "status": "paid", "...": "o recurso serializado" }
}

workspace_id é o workspace do recurso do evento. Um evento de workspace só chega aos endpoints cadastrados naquele workspace; um evento da organização (workspace_id: null, como workspace.created) chega aos endpoints de todos os workspaces.

E os headers:

Content-Type: application/json
User-Agent: Kobana-Dunning-Webhooks/1.0
X-Kobana-App: dunning
X-Kobana-Environment: production
X-Kobana-Webhook-Id: 7c1e9d2a-…      (UUID do endpoint cadastrado)
X-Kobana-Event: charge.paid
X-Kobana-Event-Id: 3d1f0c9a-…        (UUID do evento — o mesmo em todos os retries)
X-Kobana-Delivery-Id: 9b2e4a10-…     (UUID da entrega — único por evento × endpoint)
X-Kobana-Timestamp: 1753272000       (unix, segundos — momento da assinatura)
X-Kobana-Signature: v1,<base64 do HMAC-SHA256 de "delivery_id.timestamp.body">
webhook-id / webhook-timestamp / webhook-signature   (os mesmos valores, layout Standard Webhooks)

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 /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-Kobana-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.