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 4 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out)
- 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)
| 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) |
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": {}
}