Pular para o conteúdo principal

​
O que são Webhooks

Webhooks permitem que o NTX Pay envie notificações HTTPS para o seu servidor sempre que um evento relevante ocorre — confirmação de cash-in, falha de cash-out, etc. — sem você precisar fazer polling em GET /api/spei/transaction/{externalId}.

​
Eventos Disponíveis (verificar se tem mais eventos a serem adicionados)

EventoQuando dispara
cash_inSPEI cash-in confirmado ou OXXO cash-in pago no caixa
cash_outSPEI cash-out liquidado
refund_inEstorno recebido (uma transação cash-out sua foi devolvida)
refund_outEstorno enviado (você devolveu um cash-in)
internal_transferTransferência interna entre contas NTX Pay

​
Configuração

Endpoint: POST /api/webhooks-config. Você fornece:
  • url — endpoint HTTPS no seu servidor
  • events — array com 1 a 5 eventos
  • secret — opcional. Se omitido, o NTX Pay gera um automaticamente e retorna na resposta.
Veja o guia de Setup para o passo a passo.

​
Segurança — Assinatura HMAC

Todo webhook é assinado com HMAC-SHA256 usando o secret. Headers enviados:
HeaderConteúdo
X-NTXPay-Signaturesha256=<hex-hmac> do corpo bruto
X-NTXPay-Timestamptimestamp Unix do envio
X-NTXPay-Eventnome do evento (cash_in, etc.)
X-NTXPay-DeliveryUUID único do envio (use para dedupe)
Sempre valide a assinatura antes de processar — sem isso, qualquer pessoa pode falsificar notificações.

​
Garantias de Entrega

  • At-least-once: você pode receber o mesmo evento mais de uma vez. Use X-NTXPay-Delivery para deduplicar.
  • Retries: até 5 tentativas em backoff exponencial se você responder com status diferente de 2xx.
  • Timeout: 10 segundos. Responda rápido — processe assincronamente se necessário.
  • Order: os eventos chegam fora de ordem em condições de erro. Confira createdAt no payload.

​
Práticas Recomendadas

  1. Responda 200 imediatamente após validar a assinatura e enfileirar o evento.
  2. Deduplique por X-NTXPay-Delivery ou transaction.id.
  3. Idempotência: processe cash_in confirmado para o mesmo externalId uma única vez.
  4. Re-consulte GET /api/spei/transaction/{externalId} se tiver dúvida sobre estado — webhook é uma otimização, não a fonte da verdade.
  5. HTTPS obrigatório — webhooks só são enviados a URLs com protocolo HTTPS.

​
Próximos Passos

Setup de Webhook

Configure o endpoint na sua conta

Implementação

Exemplos em Node.js, Python, Java e Go de validação HMAC