Visão Geral de Webhooks

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, devolução — sem você precisar fazer polling.

Tipos de Webhook

Ao registrar um webhook via POST /api/webhooks-config, você escolhe qual tipo de evento aquela URL recebe:

Tipo	Recebe
`cash_in`	Resultado de cobranças SPEI (confirmada, rejeitada, pendente)
`cash_out`	Resultado de envios SPEI (liquidado, rejeitado, pendente)
`refund_in`	Devolução de um cash-in — um pagamento que você recebeu foi estornado ao pagador
`refund_out`	Devolução de um cash-out — uma transferência que você enviou foi devolvida pela contraparte
`all`	Geral — uma única URL que recebe todos os eventos acima

Cada webhook assina exatamente um tipo. Para receber vários tipos em URLs separadas, crie um webhook por tipo — ou use all para centralizar tudo em uma URL e rotear pelo campo event do payload.

Payload

Todo webhook entrega o mesmo formato de payload:

{
  "event": "transaction.cash_in.settled",
  "transactionId": "12345",
  "amount": 50000,
  "currency": "MXN",
  "status": "LIQUIDATED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": "646180123456789012",
  "payerName": "Juan Perez",
  "reference": "1234567",
  "voucher": "CEP20260512A1B2C3",
  "occurredAt": "2026-05-12T14:31:05.000Z"
}

string

Tipo do evento: transaction.cash_in.settled, transaction.cash_in.rejected, transaction.cash_in.returned, transaction.cash_out.settled, transaction.cash_out.rejected, transaction.cash_out.returned, ou as variantes .pending. Use este campo para rotear o processamento.

string

Identificador da transação. Correlacione com o id retornado na criação da cobrança/transferência.

integer

Valor em centavos MXN.

string

LIQUIDATED (liquidado), REJECTED (rejeitado), RETURNED (devolvido), EXPIRED (expirado sem pagamento) ou PENDING (em processamento).

string

CLABEs de destino e origem da transferência. Podem vir null dependendo do fluxo.

string

Nome de quem pagou (cash-in), quando informado pela rede. Pode vir null.

string

Referência numérica SPEI e comprovante, quando disponíveis.

string

Timestamp ISO 8601 do evento.

Headers

Header	Conteúdo
`x-event-id`	UUID único do evento — use para deduplicar
`X-NTXPay-Signature`	`sha256=<hex-hmac>` do corpo bruto, assinado com o `secret` do webhook
`Content-Type`	`application/json`

Sempre valide a assinatura antes de processar — sem isso, qualquer pessoa pode falsificar notificações. Veja Implementação.

Garantias de Entrega

At-least-once: você pode receber o mesmo evento mais de uma vez. Deduplique por x-event-id.
Retries: até 5 tentativas em backoff exponencial (a partir de ~5s) se você responder com status diferente de 2xx.
Timeout: 10 segundos. Responda rápido — processe assincronamente se necessário.
Ordem: eventos podem chegar fora de ordem em condições de erro. Confira occurredAt no payload.

Práticas Recomendadas

Responda 200 imediatamente após validar a assinatura e enfileirar o evento.
Deduplique por x-event-id.
Roteie pelo campo event — não presuma que uma URL recebe um único tipo (especialmente com all).
Trate status explicitamente — implemente os quatro estados (LIQUIDATED, REJECTED, RETURNED, PENDING).
HTTPS obrigatório — webhooks só são enviados a URLs com protocolo HTTPS.

Guia

Sandbox

Webhooks

Autenticação

SPEI

Webhooks Config

Visão Geral de Webhooks

O que são Webhooks

Tipos de Webhook

Payload

Headers

Garantias de Entrega

Práticas Recomendadas

Próximos Passos

Configuração

Implementação

​O que são Webhooks

​Tipos de Webhook

​Payload

​Headers

​Garantias de Entrega

​Práticas Recomendadas

​Próximos Passos

Configuração

Implementação

O que são Webhooks

Tipos de Webhook

Payload

Headers

Garantias de Entrega

Práticas Recomendadas

Próximos Passos