Skip to main content

Princípios

Toda implementação de webhook precisa cobrir 3 coisas:
  1. Validação HMAC com o secret recebido na criação do webhook
  2. Resposta rápida (200 OK em ≤10s)
  3. Idempotência via header x-event-id

Exemplos de Código

Por que raw body?

O HMAC é calculado sobre os bytes exatos que o NTX Pay enviou. Se o framework parsear o JSON antes (rearranjando espaços, reordenando campos), a assinatura não bate. Sempre capture o body bruto em bytes antes de fazer parse.

Roteando por Evento e Status

O campo event identifica o fluxo (transaction.cash_in.* / transaction.cash_out.*) e o status o resultado. Filtre antes de processar:

Re-Tentativas

Se você devolver status ≠ 2xx (ou estourar o timeout de 10s), o NTX Pay retenta até 5 vezes em backoff exponencial a partir de ~5 segundos. Depois disso, a entrega é marcada como falha — o reenvio manual pode ser solicitado ao suporte.
Não use 429 para sinalizar rate-limit do seu próprio serviço — isso aciona retry e amplifica a carga. Responda 503 Service Unavailable se realmente não puder processar.

Boas Práticas

  • Use Redis/banco para dedupe com TTL ≥ 24h (não memória in-process)
  • Processe assíncrono: webhook handler só valida + enfileira
  • Monitore latência do handler — alvo P95 < 500ms
  • Logue x-event-id para auditoria