Visão Geral
A configuração de webhooks é feita via quatro endpoints:GET /api/webhooks-config— listar webhooks ativosPOST /api/webhooks-config— criar/configurar um webhookPOST /api/webhooks-config/test— disparar um webhook de teste assinadoDELETE /api/webhooks-config/{id}— remover um webhook
Criar Webhook
Request
Response (201)
Campos
string
obrigatório
URL HTTPS do endpoint que receberá os webhooks. HTTP simples é rejeitado.
array
obrigatório
Um webhook assina exatamente UM evento — o array deve conter um único item. Valores aceitos:
cash_in, cash_out, refund_in, refund_out, all (Geral — recebe todos os eventos) e internal_transfer. Veja a semântica de cada tipo na Visão Geral.string
Secret HMAC para validar assinatura. Mínimo 8 caracteres, máximo 128. Se omitido, o NTX Pay gera.
Webhook de Teste
Depois de criar o webhook, dispare uma entrega de teste assinada com o mesmo secret — sem precisar movimentar uma transação:string
obrigatório
Qual webhook recebe o teste:
cash_in, cash_out, refund_in, refund_out ou internal_transfer.string
Status simulado no payload:
LIQUIDATED (default), PENDING, REJECTED ou RETURNED.string
URL temporária de teste (ex.: webhook.site). Se omitida, entrega na URL configurada.
integer
Valor em centavos no payload de teste (default
1000 = $10,00 MXN).delivered: true significa que o seu endpoint respondeu 2xx. statusCode: 0 indica erro de conexão.
Listar Webhooks
A resposta da listagem não inclui o
secret — ele só é exibido na criação.Remover Webhook
Múltiplos Webhooks
Cada webhook assina exatamente um evento, então você tem duas estratégias:- Um webhook por tipo (ex.: um para
cash_in, outro paracash_out) — roteia cada tipo para seu próprio endpoint/handler. - Um webhook
all— uma URL única recebe tudo e o seu handler roteia pelo campoeventdo payload.
Validando o Endpoint
Antes de liberar o webhook para receber tráfego de verdade:- Use webhook.site ou ngrok para inspecionar o tráfego (o campo
overrideUrldo webhook de teste aceita essas URLs) - Dispare entregas com
POST /api/webhooks-config/testvariando ostatus - Confira que sua aplicação:
- Valida
X-NTXPay-Signaturecorretamente - Retorna
200em menos de 10 segundos - Deduplica por
x-event-id
- Valida
Próximos Passos
Implementação
Validação HMAC em Node.js, Python, Java e Go
Eventos
Payload de cada tipo de evento