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 7 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out, MED Created, MED Accepted, MED Rejected)
- 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)
MedCreated
MED (Mecanismo Especial de Devolução) aberto contra transação
MedAccepted
Devolução MED aprovada
MedRejected
Devolução MED rejeitada
| 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) |
| MED Created | MedCreated | — | MED (Mecanismo Especial de Devolução) aberto contra uma transação |
| MED Accepted | MedAccepted | — | Devolução MED aprovada após análise |
| MED Rejected | MedRejected | — | Devolução MED rejeitada após análise |
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": {}
}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
MedCreated
Detalhes do evento de abertura de MED
MedAccepted
Detalhes do evento de MED aprovado
MedRejected
Detalhes do evento de MED rejeitado