Pular para o conteúdo principal

​
Visão Geral

A API de configuração de webhooks permite que você defina programaticamente onde sua aplicação receberá notificações de eventos PIX. Isso elimina a necessidade de contato com o suporte para configurar webhooks.
Mudanças na configuração de webhooks são aplicadas imediatamente. Transações subsequentes usarão a nova URL configurada.

​
Endpoint

POST /api/webhooks

​
Autenticação

Requer token Bearer da conta (Account Token) no header Authorization. 
Authorization: Bearer {account_token}
O token deve ser obtido através do endpoint de autenticação usando seu certificado de cliente.

​
Parâmetros

​
url
string
obrigatório
URL HTTPS do seu endpoint de webhook.Requisitos:
  • Deve usar protocolo HTTPS (HTTP não é aceito)
  • Deve ser uma URL válida e acessível
Exemplo: https://api.example.com/webhooks/pix
​
eventType
string
obrigatório
Tipo de evento para receber notificações.Valores possíveis:
  • cash_in - PIX recebido
  • cash_out - PIX enviado
  • refund_in - Estorno de recebimento (devolução solicitada)
  • refund_out - Devolução recebida
​
headers
array
Headers customizados para autenticação do seu endpoint (máximo 5).Cada item deve ter:
  • key: Nome do header
  • value: Valor do header
Headers bloqueados (nao permitidos):
  • host
  • content-length
  • connection
  • transfer-encoding
  • content-type
  • user-agent

​
Exemplo de Request

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

​
Exemplo de Response

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

​
Comportamento de Upsert

Se já existir um webhook configurado para o mesmo eventType, ele será atualizado com a nova URL e headers. Não é criado um webhook duplicado.
Ao atualizar um webhook existente, os headers anteriores são substituídos pelos novos. Se você não enviar headers, os headers anteriores serão removidos.

​
Códigos de Erro

CódigoDescrição
400URL inválida (não é HTTPS), tipo de evento inválido, ou mais de 5 headers
401Token não fornecido ou inválido
404Conta não encontrada
500Erro interno ao configurar webhook

​
Configurando Múltiplos Eventos

Para receber notificações de múltiplos tipos de eventos, faça uma chamada para cada tipo: 
const eventTypes = ['cash_in', 'cash_out', 'refund_in', 'refund_out'];

for (const eventType of eventTypes) {
  await fetch('https://api.ntxpay.com/api/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accountToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://api.example.com/webhooks/pix',
      eventType,
      headers: [
        { key: 'X-Webhook-Secret', value: 'abc123' },
      ],
    }),
  });
}
Você pode usar a mesma URL para todos os tipos de evento e diferenciar pelo campo type no payload do webhook.

​
Próximos Passos

Estrutura do Payload

Entenda a estrutura dos webhooks recebidos

Implementacao

Exemplos de codigo para processar webhooks

Reenviar Webhook

Reenvie webhooks perdidos ou para testes

Cash-In Webhook

Detalhes do webhook de PIX recebido