Los webhooks son geniales, hasta que su servidor de destino falla o se cae la conexión de red. Los webhooks operan por naturaleza cerca del principio de “enviar y olvidar” (fire and forget), pero en procesos comerciales críticos (como recibir pagos), “olvidar” no es una opción.

En este artículo, examinaremos cómo puede hacer que su arquitectura de webhook sea más resistente y cómo reducir la pérdida de datos al 0%.

1. Gestión de Tiempo de Espera (Timeout)

El servicio que envía el webhook no espera una respuesta para siempre. Por lo general, hay un período de tiempo de espera de 5 a 10 segundos. Si su endpoint no responde dentro de este tiempo, la solicitud se considera fallida.

Solución: Nunca realice operaciones de larga duración (creación de PDF, envío de correos electrónicos, informes de base de datos) en el endpoint que recibe el webhook. Lo único que debe hacer es:

Recibir la solicitud.
Ponerla en la cola (Queue).
Devolver 200 OK al remitente.
Realizar la operación en segundo plano (Background Worker).

2. Mecanismo de Reintento (Retry)

Todo sistema puede fallar. Su servidor podría estar en mantenimiento o podría haber un error de red instantáneo. En estos casos, el webhook no debe perderse.

Exponential Backoff: En lugar de intentar una solicitud fallida nuevamente de inmediato, el método más saludable es intentar aumentando el tiempo de espera.

1er Intento: Error
2do Intento: Después de 5 segundos
3er Intento: Después de 30 segundos
4to Intento: Después de 5 minutos

Definitivamente revise la política de reintento de su proveedor de webhook (por ejemplo, Stripe). También configure definitivamente una estrategia de reintento en sus propios envíos de webhook.

3. Idempotencia

El mecanismo de reintento es excelente pero tiene un efecto secundario peligroso: La misma solicitud llega más de una vez. Si la respuesta 200 OK no llega al remitente debido a un error de red, el remitente envía el mismo webhook nuevamente. Si su código no está preparado para esto, podría cobrarle al cliente dos veces o crear registros duplicados en la base de datos.

Solución: Hay una ID única (Event ID) en cada solicitud de webhook. Mantenga esta ID en su base de datos o Redis.

if redis.exists(event_id) {
    return 200 OK; // Ya procesado, no hacerlo de nuevo.
}
process_payment();
redis.save(event_id);

4. Seguridad y Verificación (HMAC)

Dado que su endpoint es público, personas malintencionadas pueden enviar solicitudes de webhook falsas. Para evitar esto, es obligatorio verificar la firma HMAC (Hash-based Message Authentication Code). El remitente aplica hash al payload con una clave secreta y lo envía en el encabezado. Usted realiza la misma operación y verifica si coincide.

5. Dead Letter Queue (DLQ)

¿Qué sucede si todos los intentos de reintento fallan? En lugar de eliminar los datos, muévalos a un área separada llamada “Dead Letter Queue”. Puede examinar manualmente los registros erróneos aquí más tarde y procesarlos nuevamente después de resolver el problema.

Resumen

Construir una arquitectura de webhook confiable requiere gestión de colas, estrategias de reintento y medidas de seguridad.

Si no desea construir toda esta infraestructura (Queue, Retry, DLQ, Logging) desde cero, puede usar una Pasarela de Webhook como WebhookIO. WebhookIO recibe todas las solicitudes entrantes por usted, las pone en cola y se las entrega de forma segura cuando su endpoint está listo.

Medidas críticas para evitar perder solicitudes Webhook