Pular para o conteúdo principal

​
Visão Geral

A configuração de webhooks é feita via três endpoints:
  • GET /api/webhooks-config — listar webhooks ativos
  • POST /api/webhooks-config — criar/configurar um webhook
  • DELETE /api/webhooks-config/{id} — remover um webhook

​
Criar Webhook

​
Request

curl -X POST https://sandbox.ntxpay.com/api/webhooks-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-servidor.com/webhooks/ntxpay",
    "events": ["cash_in", "cash_out"],
    "secret": "whsec_abc123def456"
  }'

​
Response (201)

{
  "id": 42,
  "url": "https://meu-servidor.com/webhooks/ntxpay",
  "events": ["cash_in", "cash_out"],
  "isActive": true,
  "secret": "whsec_abc123def456"
}
Se você omitir secret no request, o NTX Pay gera automaticamente e retorna na resposta — guarde imediatamente, ele não é exibido novamente.

​
Campos

​
url
string
obrigatório
URL HTTPS do endpoint que receberá os webhooks. HTTP simples é rejeitado.
​
events
array
obrigatório
Lista de 1 a 5 eventos. Valores aceitos: cash_in, cash_out, refund_in, refund_out, internal_transfer.
​
secret
string
Secret HMAC para validar assinatura. Mínimo 8 caracteres, máximo 128. Se omitido, o NTX Pay gera.

​
Listar Webhooks

curl -X GET https://sandbox.ntxpay.com/api/webhooks-config \
  -H "Authorization: Bearer $TOKEN"

{
  "accountId": 93,
  "webhooks": [
    {
      "id": 42,
      "url": "https://meu-servidor.com/webhooks/ntxpay",
      "events": ["cash_in", "cash_out"],
      "isActive": true,
      "createdAt": "2026-05-01T10:30:00.000Z"
    }
  ],
  "total": 1
}
A resposta da listagem não inclui o secret — ele só é exibido na criação.

​
Remover Webhook

curl -X DELETE https://sandbox.ntxpay.com/api/webhooks-config/42 \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Webhook removido com sucesso"
}

​
Múltiplos Webhooks

Você pode configurar vários webhooks simultaneamente, cada um com seu conjunto de eventos. Útil para:
  • Separar logs/auditoria (recebe todos os eventos) de processamento (só cash_in/cash_out)
  • Múltiplos serviços consumindo eventos diferentes
  • Ambientes internos distintos (ex.: dev vs homologação interna)

​
Testando o Endpoint

Antes de liberar o webhook para receber tráfego de verdade, valide seu endpoint:
  1. Use webhook.site ou ngrok para inspecionar o tráfego
  2. Dispare cobranças com X-Sandbox-Scenario (veja Testes em Sandbox)
  3. Confira que sua aplicação:
    • Valida X-NTXPay-Signature corretamente
    • Retorna 200 em menos de 10 segundos
    • Deduplica por X-NTXPay-Delivery

​
Próximos Passos

Implementação

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

Eventos

Payload de cada tipo de evento