Introducción a Webhooks

Los webhooks de Forpay notifican eventos del ciclo de vida de un compromiso de pago a las URLs configuradas para tu integración. Tu sistema puede utilizarlos para procesar activaciones y cobros y complementar la conciliación mediante consultas de estado.

¿Cómo funciona?

Cuando integras con Forpay, proporcionas dos URLs de callback durante la creación de cada mandato:

activationWebhook: Recibe una notificación cuando un cliente completa el enrolamiento de su medio de pago (tarjeta, cuenta bancaria, etc.).
paymentWebhook: Recibe una notificación cada vez que se procesa el cobro de una cuota (exitosa, rechazada, en proceso, etc.).

Forpay envía un POST con un cuerpo JSON para los eventos habilitados para tu comercio. Coordina esa habilitación con Forpay junto con la configuración de las URLs. Informar una URL por sí solo no habilita todos los eventos.

Tipos de eventos

Webhook de Activación

Se dispara cuando un compromiso de pago cambia de estado. El caso más común es la activación del mandato tras el enrolamiento exitoso del medio de pago del cliente.

Los métodos de pago que generan este evento son:

Método de Pago	ID
Tarjeta de Crédito	3
Tarjeta de Débito	4
Tarjeta de Prepago	11
Débito Directo (PAC)	5
ForPAC	6
PAC directo	14

Webhook de Pagos

Se dispara cada vez que una cuota de un mandato activo es procesada. Puede indicar que el cobro fue exitoso, rechazado, está en proceso o ha sido revertido.

Flujo general de integración

Tu sistema                       Forpay
─────────────────────────────────────────────────────
1. Autenticación        →   POST /login  →  Obtiene JWT
2. Crear usuario        →   POST /user
3. Crear mandato        →   POST /mandate
   (incluye activationWebhook y paymentWebhook)
4. Cliente enrola       ←   Forpay envía POST a activationWebhook
5. Cobro procesado      ←   Forpay envía POST a paymentWebhook

Consideraciones importantes

Todas las notificaciones incluyen un campo signature con una firma HMAC-SHA256 que debes validar para garantizar que el mensaje proviene legítimamente de Forpay. Ver Verificación HMAC.
Tu endpoint debe responder con un código HTTP 2xx para que Forpay registre la notificación como entregada exitosamente.
Usa la consulta de estado por API como apoyo para conciliar los eventos que tu sistema no haya recibido o procesado.
Valida el HMAC y guarda durablemente el evento antes de responder, idealmente en menos de dos segundos. Procesa las tareas más lentas después del acuse.
Configura una URL HTTPS para cada receptor.
Los datos sensibles (como fileBase64 en activaciones ForPAC) deben ser procesados y almacenados de forma segura.