Descripción General
¿Qué son los Webhooks?
Los Webhooks PIX le permiten recibir notificaciones en tiempo real cuando cambia el estado de una transacción PIX. En lugar de consultar constantemente la API, su sistema es notificado automáticamente cuando ocurren eventos importantes.
Los webhooks son la forma recomendada de rastrear estados de transacciones. Reducen la latencia y el consumo de recursos en comparación con el polling.
Características
- Notificaciones en tiempo real
- Soporte para 7 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out, MED Created, MED Accepted, MED Rejected)
- Reintentos automáticos en caso de fallo
- Autenticación Basic Auth
- Payload JSON estandarizado
Eventos Disponibles
CashIn
Recepción PIX confirmada (CREDIT)
CashOut
Envío PIX confirmado (DEBIT)
CashInReversal
Reversión de recepción (DEBIT)
CashOutReversal
Reversión de envío recibida (CREDIT)
MedCreated
MED (Mecanismo Especial de Devolución) abierto contra una transacción
MedAccepted
Devolución MED aprobada
MedRejected
Devolución MED rechazada
| Evento | event | movementType | Descripción |
|---|---|---|---|
| PIX In | CashIn | CREDIT | Recepción PIX confirmada |
| PIX Out | CashOut | DEBIT | Envío PIX confirmado |
| Refund In | CashInReversal | DEBIT | Reversión de recepción (devolución iniciada por usted) |
| Refund Out | CashOutReversal | CREDIT | Reversión de envío (devolución recibida) |
| MED Created | MedCreated | — | MED (Mecanismo Especial de Devolución) abierto contra una transacción |
| MED Accepted | MedAccepted | — | Devolución MED aprobada tras el análisis |
| MED Rejected | MedRejected | — | Devolución MED rechazada tras el análisis |
Configuración del Endpoint
Para recibir webhooks, necesita:
Use la API de Configuración de Webhooks para definir la URL de su endpoint programáticamente.
Cree un endpoint HTTPS que acepte solicitudes POST y retorne HTTP 200 rápidamente.
Configure la validación del encabezado Basic Auth.
Requisitos Técnicos
| Requisito | Descripción |
|---|---|
| Protocolo | HTTPS obligatorio |
| Método | POST |
| Timeout | Responder dentro de 10 segundos |
| Respuesta | HTTP 200 OK |
| Content-Type | application/json |
Si su endpoint no responde con HTTP 200 dentro de 10 segundos, el webhook se considerará un fallo y será reintentado.
Autenticación Basic Auth
Los webhooks se envían con autenticación Basic Auth en el encabezado:
Authorization: Basic base64(username:password)// Node.js/Express - Validation
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');
}
// Process webhook...
res.status(200).json({ acknowledged: true });
});Estructura Base del Payload
Todos los webhooks comparten una estructura base común:
{
"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 Pasos
Configurar Webhooks
Configure URLs de webhook vía API
CashIn
Detalles del evento de recepción
CashOut
Detalles del evento de envío
CashInReversal
Detalles del evento de devolución
CashOutReversal
Detalles del evento de reversión
MedCreated
Detalles del evento de apertura de MED
MedAccepted
Detalles del evento de MED aprobado
MedRejected
Detalles del evento de MED rechazado