Visão Geral
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)
| Evento | event | movementType | Descrição |
|---|---|---|---|
| PIX In | CashIn | CREDIT | Recebimento PIX confirmado |
| PIX Out | CashOut | DEBIT | Envio PIX confirmado |
| Refund In | CashInReversal | DEBIT | Estorno de recebimento (devolução iniciada por você) |
| Refund Out | CashOutReversal | CREDIT | Devolução de envio (devolução recebida) |
Configuração do Endpoint
Para receber webhooks, você precisa:
Use a API de Configuração de Webhooks para definir a URL do seu endpoint programaticamente.
Crie um endpoint HTTPS que aceite requisições POST e retorne HTTP 200 rapidamente.
Configure a validação do header de autenticação Basic Auth.
Requisitos Técnicos
| Requisito | Descrição |
|---|---|
| Protocolo | HTTPS obrigatório |
| Método | POST |
| Timeout | Responder em até 10 segundos |
| Response | HTTP 200 OK |
| Content-Type | application/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": {}
}