Skip to main content

Visão Geral

A configuração de webhooks é feita via quatro endpoints:
  • GET /api/webhooks-config — listar webhooks ativos
  • POST /api/webhooks-config — criar/configurar um webhook
  • POST /api/webhooks-config/test — disparar um webhook de teste assinado
  • DELETE /api/webhooks-config/{id} — remover um webhook

Criar Webhook

Request

Response (201)

Se você omitir secret no request, o NTX Pay gera automaticamente e retorna na resposta — guarde imediatamente, ele não é exibido novamente.

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 para cash_out) — roteia cada tipo para seu próprio endpoint/handler.
  • Um webhook all — uma URL única recebe tudo e o seu handler roteia pelo campo event do payload.

Validando o Endpoint

Antes de liberar o webhook para receber tráfego de verdade:
  1. Use webhook.site ou ngrok para inspecionar o tráfego (o campo overrideUrl do webhook de teste aceita essas URLs)
  2. Dispare entregas com POST /api/webhooks-config/test variando o status
  3. Confira que sua aplicação:
    • Valida X-NTXPay-Signature corretamente
    • Retorna 200 em menos de 10 segundos
    • Deduplica por x-event-id

Próximos Passos

Implementação

Validação HMAC em Node.js, Python, Java e Go

Eventos

Payload de cada tipo de evento