Configurar Webhooks
Descripción General
El registro de las URLs de webhook se hace exclusivamente en el panel (https://banking.fypay.me), en Configuración → Webhooks. No existe endpoint de API para registrar, listar o eliminar webhooks, ni para generar la clave de firma.
Los cambios en la configuración de webhooks se aplican inmediatamente. Los eventos posteriores usarán las URLs configuradas.
Registrar un webhook
Ingrese en https://banking.fypay.me y abra Configuración → Webhooks.
Seleccione el tipo de evento que recibirá la URL:
cash_in- PIX recibidocash_out- PIX enviadorefund_in- Reverso de recepciónrefund_out- Devolución recibidamed_created- MED (Mecanismo Especial de Devolución) abierto contra una transacción recibidamed_accepted- Solicitud de devolución MED aprobadamed_rejected- Solicitud de devolución MED rechazada
Informe la URL de su endpoint. Debe usar HTTPS (HTTP no es aceptado) y ser una URL pública válida (las direcciones privadas o internas son rechazadas).
Ejemplo: https://api.example.com/webhooks/pix
Registre hasta 5 headers que se enviarán en todo webhook de esta URL. Útiles para autenticar la llamada en su endpoint (por ejemplo, Authorization o X-Webhook-Secret).
- Nombre del header: solo letras, números,
-y_ - Valor del header: no puede estar vacío
- Headers bloqueados:
host,content-length,connection,transfer-encoding,content-type,user-agent
Defina el formato del payload enviado a esta URL en los eventos de transacción:
- Estándar (valor por defecto): formato descrito en esta sección de Webhooks
- PIX BACEN: formato de la pestaña PIX BACEN
Los eventos MED usan siempre el mismo payload, independientemente de la versión.
En el mismo menú, genere la clave de firma HMAC. A partir de entonces, todo webhook incluye el header X-Avista-Signature, que debe validar en su endpoint. Vea Implementación para el paso a paso de generación, rotación y validación.
Múltiples URLs por Evento
Puede registrar hasta 3 URLs HTTPS activas para el mismo evento. Registrar una URL nueva agrega esa URL al evento; las URLs ya registradas siguen activas y no son reemplazadas.
Cuando ocurre el evento, la notificación se envía en fan-out a todas las URLs activas registradas en ese evento. Cada URL tiene su propia entrega y reintento: una falla en una URL no afecta a las demás.
Para editar los headers o la versión de una URL, o para eliminarla y liberar espacio en el límite de 3, use el mismo menú Configuración → Webhooks.
Configurando Múltiples Eventos
Para recibir notificaciones de varios tipos de evento, registre la URL en cada evento deseado en el panel.
Puede usar la misma URL para todos los tipos de evento y diferenciarlos por el campo event en el payload del webhook.
Próximos Pasos
Descripción General
Eventos, autenticación, allowlist de IPs y estructura del payload
Implementación
Ejemplos de código para procesar webhooks y validar la firma
Reenviar Webhook
Reenvíe webhooks perdidos o para pruebas
Cash-In Webhook
Detalles del webhook de PIX recibido
Webhooks MED
Reciba notificaciones sobre eventos MED (Mecanismo Especial de Devolución)