Pular para o conteúdo principal

​
O que são Webhooks?

Os Webhooks PIX permitem que você receba notificações em tempo real quando o status de uma transação PIX muda. Em vez de fazer polling constantemente na API, seu sistema é notificado automaticamente quando eventos importantes ocorrem.
Webhooks são a forma recomendada de acompanhar o status das transações. Eles reduzem a latência e o consumo de recursos comparado ao polling.

​
Características

  • Notificações em tempo real
  • Suporte a 4 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out)
  • Retentativas automáticas em caso de falha
  • Autenticação via Basic Auth
  • Payload padronizado em JSON

​
Eventos Disponíveis

CashIn

Recebimento PIX confirmado (CREDIT)

CashOut

Envio PIX confirmado (DEBIT)

CashInReversal

Estorno de recebimento (DEBIT)

CashOutReversal

Devolução de envio recebida (CREDIT)
EventoeventmovementTypeDescrição
PIX InCashInCREDITRecebimento PIX confirmado
PIX OutCashOutDEBITEnvio PIX confirmado
Refund InCashInReversalDEBITEstorno de recebimento (devolução iniciada por você)
Refund OutCashOutReversalCREDITDevolução de envio (devolução recebida)

​
Configuração do Endpoint

Para receber webhooks, você precisa:
1

Configurar URL de Webhook

Use a API de Configuração de Webhooks para definir a URL do seu endpoint programaticamente.
2

Implementar Endpoint

Crie um endpoint HTTPS que aceite requisições POST e retorne HTTP 200 rapidamente.
3

Validar Autenticação

Configure a validação do header de autenticação Basic Auth.

​
Requisitos Técnicos

RequisitoDescrição
ProtocoloHTTPS obrigatório
MétodoPOST
TimeoutResponder em até 10 segundos
ResponseHTTP 200 OK
Content-Typeapplication/json
Se seu endpoint não responder com HTTP 200 dentro de 10 segundos, o webhook será considerado como falha e será retentado.

​
Autenticação Basic Auth

Os webhooks são enviados com autenticação Basic Auth no header: 
Authorization: Basic base64(username:password)

// Node.js/Express - Validação
app.post('/webhooks/pix', (req, res) => {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Basic ')) {
    return res.status(401).send('Unauthorized');
  }

  const base64Credentials = authHeader.split(' ')[1];
  const credentials = Buffer.from(base64Credentials, 'base64').toString('ascii');
  const [username, password] = credentials.split(':');

  if (username !== process.env.WEBHOOK_USER || password !== process.env.WEBHOOK_PASS) {
    return res.status(401).send('Unauthorized');
  }

  // Processar webhook...
  res.status(200).json({ acknowledged: true });
});

​
Estrutura Base do Payload

Todos os webhooks compartilham uma estrutura base comum: 
{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "12345",
  "externalId": "PIX-5482123298-EJUYFSMU1UU",
  "endToEndId": "E00416968202512111942rjzxxzSSTD9",
  "pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
  "feeAmount": 0.01,
  "originalAmount": 0.5,
  "finalAmount": 0.49,
  "processingDate": "2025-12-11T19:42:04.080Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {}
}
​
event
string
obrigatório
Tipo do evento.Valores possíveis: CashIn, CashOut, CashInReversal, CashOutReversal
​
status
string
obrigatório
Status da transação.Valores possíveis: PENDING, CONFIRMED, ERROR
​
transactionType
string
obrigatório
Tipo de transação. Sempre PIX para webhooks PIX.
​
movementType
string
obrigatório
Tipo de movimento na conta.
  • CREDIT: Entrada de recursos (recebimento ou devolução recebida)
  • DEBIT: Saída de recursos (envio ou estorno)
​
transactionId
string
obrigatório
ID numérico da transação na NTX Pay (retornado como string).Exemplo: "12345"
​
endToEndId
string
obrigatório
ID End-to-End gerado pelo Banco Central para rastreamento.Exemplo: "E00416968202512111942rjzxxzSSTD9"
​
processingDate
string
obrigatório
Data e hora do processamento (ISO 8601 UTC).Exemplo: "2025-12-11T19:42:04.080Z"
​
feeAmount
number
obrigatório
Taxa cobrada pela transação em reais (BRL).Exemplo: 0.01
​
originalAmount
number
obrigatório
Valor original da transação em reais (BRL).Exemplo: 0.50
​
finalAmount
number
obrigatório
Valor final após aplicação de taxas.
  • Para CREDIT: originalAmount - feeAmount
  • Para DEBIT: originalAmount + feeAmount
​
externalId
string
ID externo fornecido na criação da transação.Exemplo: "PIX-5482123298-EJUYFSMU1UU"
​
pixKey
string
Chave PIX utilizada na transação (CPF, CNPJ, email, telefone ou chave aleatória).
​
errorCode
string
Código de erro quando status é ERROR. Nulo se sucesso.
​
errorMessage
string
Mensagem de erro descritiva. Nulo se sucesso.
​
metadata
object
Metadados adicionais específicos do evento.

​
Próximos Passos

Configurar Webhooks

Configure URLs de webhook via API

CashIn

Detalhes do evento de recebimento

CashOut

Detalhes do evento de envio

CashInReversal

Detalhes do evento de estorno

CashOutReversal

Detalhes do evento de devolução