Configurar webhooks da conta

Rota temporariamente desativada. Esta rota não está cadastrando webhooks no momento: ela responde 200 com success: false e a mensagem "Rota desativada", sem persistir nada. Enquanto isso, cadastre e gerencie seus webhooks pelo dashboard (https://app.ntxpay.com), em Configurações → Webhooks. O disparo das notificações de webhook continua funcionando normalmente.

POST /api/webhooks

POST https://api.ntxpay.com/api/webhooks

Requer um Bearer token no header Authorization. Veja Gerar Token para obter um.

Adiciona uma URL de webhook para um tipo de evento específico (até 3 URLs ativas por evento). Se a mesma URL já estiver cadastrada para aquele tipo de evento, ela é atualizada (headers e version) — as demais URLs cadastradas não são afetadas. No disparo, a notificação é enviada em fan-out para todas as URLs ativas do evento.

Autenticação

Requer token Bearer no header Authorization.

Eventos Disponíveis

Evento	Descrição
`cash_in`	PIX recebido
`cash_out`	PIX enviado
`refund_in`	Estorno de recebimento (devolução solicitada)
`refund_out`	Devolução recebida
`med_created`	MED (Mecanismo Especial de Devolução) aberto contra uma transação
`med_accepted`	Solicitação de devolução MED aprovada
`med_rejected`	Solicitação de devolução MED rejeitada

Request Body

Campo	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL HTTPS do endpoint que receberá os webhooks
`eventType`	string	Sim	Tipo de evento: `cash_in`, `cash_out`, `refund_in`, `refund_out`, `med_created`, `med_accepted`, `med_rejected`
`headers`	array	Não	Headers customizados para autenticação (máximo 5). Headers bloqueados: `host`, `content-length`, `connection`, `transfer-encoding`, `content-type`, `user-agent`
`headers[].key`	string	Sim	Nome do header
`headers[].value`	string	Sim	Valor do header

{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}

Exemplos de Código

cURL

curl -X POST "https://api.ntxpay.com/api/webhooks" \
  -H "Authorization: Bearer $NTXPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}'

const axios = require('axios');

const response = await axios.post('https://api.ntxpay.com/api/webhooks',
  {
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.NTXPAY_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.ntxpay.com/api/webhooks',
    headers={
        'Authorization': f'Bearer {os.environ["NTXPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
},
)
print(response.json())

$ch = curl_init('https://api.ntxpay.com/api/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('NTXPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "url": "https://api.example.com/webhooks/pix",
  "eventType": "cash_in",
  "headers": [
    { "key": "Authorization", "value": "Bearer token123" },
    { "key": "X-Webhook-Secret", "value": "abc123" }
  ]
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "url": "https://api.example.com/webhooks/pix",
      "eventType": "cash_in",
      "headers": [
        { "key": "Authorization", "value": "Bearer token123" },
        { "key": "X-Webhook-Secret", "value": "abc123" }
      ]
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.ntxpay.com/api/webhooks"))
    .header("Authorization", "Bearer " + System.getenv("NTXPAY_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response (200)

Campo	Tipo	Descrição
`success`	boolean	Indica se a operação foi bem-sucedida
`message`	string	Mensagem descritiva do resultado

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

Erros

Status	Descrição
400	Dados inválidos (URL não é HTTPS, tipo de evento inválido, mais de 5 headers, ou mais de 3 URLs ativas por evento)
401	Token não fornecido ou inválido
404	Conta não encontrada
500	Erro interno ao configurar webhook