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 hacer polling constantemente a la API, su sistema es notificado automáticamente cuando ocurren eventos importantes.
Los webhooks son la forma recomendada de seguir el estado de las transacciones. Reducen la latencia y el consumo de recursos en comparación con el polling.
Características
- Notificaciones en tiempo real, enviadas vía
POSTcon cuerpo JSON - 7 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out, MED Created, MED Accepted, MED Rejected)
- Hasta 3 URLs HTTPS por evento, con entrega a todas ellas (fan-out)
- Hasta 5 headers personalizados por URL (por ejemplo, un
Authorizationpropio) - Firma HMAC-SHA256 del cuerpo en el header
X-Avista-Signature - Reintentos automáticos en caso de falla y reenvío manual vía API
Eventos Disponibles
CashIn
Recepción PIX (CREDIT)
CashOut
Envío PIX (DEBIT)
CashInReversal
Reversión de recepción (DEBIT)
CashOutReversal
Devolució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 | eventType (registro) | event (payload) | movementType | Descripción |
|---|---|---|---|---|
| PIX In | cash_in | CashIn | CREDIT | Recepción PIX |
| PIX Out | cash_out | CashOut | DEBIT | Envío PIX |
| Refund In | refund_in | CashInReversal | DEBIT | Reversión de una recepción |
| Refund Out | refund_out | CashOutReversal | CREDIT | Devolución recibida de un envío |
| MED Created | med_created | MedCreated | — | MED abierto contra una transacción |
| MED Accepted | med_accepted | MedAccepted | — | Devolución MED aprobada |
| MED Rejected | med_rejected | MedRejected | — | Devolución MED rechazada |
El registro de URLs usa el eventType en snake_case (cash_in, cash_out...). El campo event del payload recibido usa PascalCase (CashIn, CashOut...).
Configuración del Endpoint
Para recibir webhooks, usted necesita:
Use el panel (https://banking.fypay.me), en Configuración → Webhooks (vea Configurar Webhooks). Puede registrar hasta 3 URLs HTTPS activas por evento; en el disparo, la notificación se envía a todas ellas (fan-out).
Cree un endpoint HTTPS que acepte solicitudes POST y responda con un estado 2xx en hasta 10 segundos.
Genere la clave de firma en el panel y valide el header X-Avista-Signature (vea Implementación). Opcionalmente, valide también los headers personalizados que registró y restrinja las IPs de origen.
Requisitos Técnicos
| Requisito | Descripción |
|---|---|
| Protocolo | HTTPS obligatorio en el registro |
| Método | POST |
| Content-Type | application/json |
| Timeout | 10 segundos |
| Respuesta | Cualquier estado 2xx. Las redirecciones (3xx) no se siguen y cuentan como falla |
Si su endpoint no responde con 2xx en hasta 10 segundos, la entrega se considera fallida y se reintentará después de 30 s, 1 min, 3 min, 5 min y 15 min. Cuando hay varias URLs registradas para el mismo evento, cada URL tiene su propia entrega: una falla en una URL no afecta a las demás, y una URL que ya recibió con éxito no recibe de nuevo en los reintentos.
Autenticación de los Webhooks
FyPay ofrece tres mecanismos, que pueden combinarse:
| Mecanismo | Cómo funciona |
|---|---|
| Firma HMAC (recomendado) | Después de que usted genera la clave de firma en el panel, todo webhook pasa a traer el header X-Avista-Signature con el HMAC-SHA256 (hex) del cuerpo bruto. Vea cómo validar. |
| Headers personalizados | Puede registrar hasta 5 headers por URL (por ejemplo, Authorization: Basic ... o X-Webhook-Secret: ...). Se envían en todo webhook de esa URL y su endpoint valida los valores. |
| Allowlist de IPs | Acepte solo solicitudes que provengan de las IPs de origen de FyPay (lista abajo). |
El nombre del header de firma es realmente X-Avista-Signature. Es el nombre técnico enviado hoy en todos los webhooks firmados; úselo exactamente así en su validador.
Mientras no se genere la clave de firma en el panel, los webhooks se entregan sin el header X-Avista-Signature. FyPay no envía Basic Auth por cuenta propia: si su endpoint exige Authorization, registre ese header como header personalizado.
Ejemplo de validación de un header personalizado Authorization: Basic ... que usted registró:
app.post('/webhooks/pix', (req, res) => {
const expected = 'Basic ' + Buffer.from(
`${process.env.WEBHOOK_USER}:${process.env.WEBHOOK_PASS}`
).toString('base64');
if (req.headers.authorization !== expected) {
return res.status(401).send('Unauthorized');
}
res.status(200).json({ acknowledged: true });
});Allowlist de IPs
Los webhooks de FyPay salen de las siguientes direcciones IP. Si su firewall o WAF restringe el tráfico entrante, libere todas ellas:
| IP de origen |
|---|
184.197.16.190 |
54.85.39.76 |
184.197.130.162 |
184.196.180.161 |
52.0.159.232 |
54.88.75.254 |
Libere la lista completa: el envío puede salir de cualquiera de estas IPs. La allowlist complementa la validación de la firma, pero no la sustituye.
Estructura Base del Payload
Los eventos de transacción (CashIn, CashOut, CashInReversal, CashOutReversal) comparten la estructura base siguiente. Los eventos MED tienen un payload propio, descrito en MedCreated.
{
"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,
"mismatchAmount": null,
"processingDate": "2025-12-11T19:42:04.080Z",
"errorCode": null,
"errorMessage": null,
"providerId": "a1b2c3d4e5",
"metadata": {}
}Los valores monetarios se envían en reales (BRL), con hasta 5 decimales.
Además de la base, CashIn y CashOut traen el objeto counterpart, y CashInReversal y CashOutReversal traen el objeto parentTransaction.
Próximos Pasos
Configurar Webhooks
Configure URLs de webhook vía API
Implementación
Validación de la firma, idempotencia y reintentos
CashIn
Detalles del evento de recepción
CashOut
Detalles del evento de envío
CashInReversal
Detalles del evento de reversión
CashOutReversal
Detalles del evento de devolución
MedCreated
Detalles del evento de apertura de MED
MedAccepted
Detalles del evento de MED aprobado
MedRejected
Detalles del evento de MED rechazado