Webhooks (Eventos Recebidos)

Para devs integrando o webhook: nesta pasta cada item NÃO é uma chamada à API Dotfy — é um exemplo do payload que SUA aplicação receberá em POST no endpoint configurado em /api/webhook-endpoints.

Envelope comum a todos os eventos

POST https://seu-dominio.com/webhooks/dotfy
Content-Type: application/json
X-Webhook-Signature: t=1714000000000,v1=ab12cd34...           ← assinatura HMAC-SHA256 (ver abaixo)
X-Webhook-Event: EVENT:CHARGE_PAID                            ← nome do evento
X-Webhook-ID: clev01h2k3m4n5p6q7r8s9t0u1                      ← ID único do evento (use para deduplicar)
X-Webhook-Timestamp: 2026-05-07T14:35:12.000Z                 ← horário de emissão (ISO 8601)

{
  "event": "EVENT:<NOME>",
  "timestamp": "2026-05-07T14:35:12.000Z",
  "data": { ... }
}

Como funciona a assinatura

O header X-Webhook-Signature segue o formato t=<timestamp_ms>,v1=<hex> onde:

<timestamp_ms> é o timestamp em milissegundos no momento da assinatura.

<hex> é HMAC_SHA256(secret, "<timestamp_ms>.<body_bruto>") em hex lowercase.

secret é o valor whsec_... retornado uma única vez quando você criou o endpoint via POST /api/webhook-endpoints.

Validação (Node.js)

IMPORTANTE: passe o body bruto (string original recebida no request) — re-serializar o JSON quebra a assinatura.

Idempotência

Use X-Webhook-ID (ou data.id do payload) como chave de deduplicação. Em caso de retry, o mesmo X-Webhook-ID chegará novamente.

Política de retry

Falha (status ≥ 500 ou timeout > 10s): retry com backoff exponencial até 5 tentativas. Após isso, vai para a DLQ — você pode reenviar via dashboard.

Lista de eventos

Os 10 itens abaixo cobrem todos os eventos disparados hoje. O shape de data é o definido pelo gateway e respeitado por todos os adquirentes (Woovi, Treeal, Asaas, Simpay).

Envelope comum a todos os eventos#

Como funciona a assinatura#

Validação (Node.js)#

Idempotência#