Esta página reúne las recomendaciones clave para construir una integración robusta, confiable y segura con los webhooks de Forpay.
Idempotencia
Tu receptor debe distinguir una retransmisión del mismo evento de un nuevo pago o cambio de estado de la misma cuota. Conserva las referencias de mandato, cuota y pago disponibles, el estado y la fecha del evento para contrastarlo con tu registro de recepción.
Una cuota puede tener varios pagos, intentos o transiciones. Deduplicar solo por installment.internalId, o por mandato más cuota, puede descartar eventos válidos. Define el criterio por tipo de evento y conserva el payload recibido para reconciliar los casos ambiguos. El campo signature se usa para verificar el HMAC y no identifica de forma única el evento.
Al reintentar tu procesamiento interno, reutiliza el registro de recepción y haz que las escrituras de negocio sean idempotentes.
Renotificaciones
Una misma cuota puede aparecer en notificaciones de pagos, rechazos, cobro en proceso o reversas. Conserva el historial de eventos, sus referencias y sus fechas para aplicar cada transición según corresponda.
La repetición del estado por sí sola no demuestra que se trate del mismo evento. Contrasta los eventos ambiguos o recibidos fuera de orden con las consultas de estado de la API antes de sobrescribir información conciliada.
Respuesta rápida al webhook
Valida el HMAC, guarda durablemente el evento y responde con HTTP 2xx, idealmente en menos de dos segundos. Este tiempo es una recomendación para el acuse de recepción. Realiza el procesamiento pesado mediante una cola o un worker después de confirmar el guardado.
app.post('/webhook/forpay', async (req, res) => {
if (!validateHmac(req.body, HMAC_SECRET, req.body.signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
try {
// La implementación debe confirmar persistencia antes de devolver éxito.
await inbox.saveForProcessing(req.body);
return res.sendStatus(204);
} catch (error) {
return res.sendStatus(500);
}
});El ejemplo requiere una bandeja de entrada durable y un worker propios de tu integración.
Validar siempre la firma HMAC
Verifica signature antes de aceptar y procesar el evento, también en desarrollo. El HMAC autentica el conjunto de campos y el orden definidos en la receta correspondiente. Comprueba además la estructura y los valores que tu integración utiliza.
Si la firma no coincide, rechaza la solicitud y conserva el diagnóstico necesario para investigarla. El ejemplo de recepción anterior muestra el orden de validación, guardado y acuse. Ver Verificación HMAC.
No confiar únicamente en el webhook para confirmar pagos
El webhook es el mecanismo principal de notificación, pero pueden ocurrir demoras, pérdidas de conectividad o fallos temporales en tu servidor. Por eso se recomienda implementar una conciliación periódica consultando el estado de las cuotas directamente a la API de Forpay (GET /mandate/{mandateTypeId}/{mandateId}), especialmente para cuotas críticas o de alto monto.
Manejo de errores y reintentos en tu lado
Implementa un registro durable de recepción y de fallos de procesamiento para poder reintentar las tareas de tu integración. Complementa la recuperación con consultas de estado y la coordinación con Forpay cuando falten eventos.
async function processWebhookAsync(payload) {
try {
await upsertInstallmentState(payload);
} catch (err) {
// Registrar el fallo para revisión o reprocesamiento manual
await db.failedWebhooks.create({
payload: JSON.stringify(payload),
error: err.message,
receivedAt: new Date(),
});
}
}Seguridad del endpoint
- Usa HTTPS en tu URL de webhook como requisito de integración.
- Evita exponer en logs el contenido completo del payload, ya que puede contener datos sensibles del cliente (RUT, número de cuenta).
- Si es posible, restringe el acceso al endpoint a las IPs de Forpay (consulta a tu ejecutivo de integración la lista de IPs permitidas).
Resumen de buenas prácticas
| Práctica | Descripción |
|---|---|
| Idempotencia | Distingue eventos y pagos de una misma cuota mediante sus referencias, estado y fecha. |
| Aceptar renotificaciones | No bloquees estados repetidos ni limites a un solo tipo de estado. |
| Responder rápido | Valida el HMAC y guarda el evento antes del acuse 2xx, idealmente en menos de dos segundos. |
| Validar HMAC | Siempre verifica signature antes de procesar el evento. |
| Conciliación activa | Consulta el estado de cuotas por API como respaldo ante fallos de webhook. |
| Registro de fallos | Almacena notificaciones no procesadas para reprocesamiento manual. |
| HTTPS y seguridad | Usa HTTPS, evita loguear datos sensibles, restringe IPs si es posible. |