Webhooks explicados: cargas firmadas y reintentos
Acabas de integrar un proveedor de pagos o un servicio de CI/CD, y ahora necesitas recibir eventos en tiempo real. Los webhooks son la forma estándar de enviar datos entre sistemas, pero muchas implementaciones fallan en producción debido a fallos de seguridad o entregas poco confiables. Esta guía explica cómo proteger los webhooks con cargas firmadas e implementar mecanismos de reintento robustos.
¿Qué son los webhooks y por qué importan?
Un webhook es una llamada HTTP: cuando ocurre un evento en un sistema de origen (por ejemplo, un nuevo pedido), envía una solicitud HTTP POST a una URL que proporciones. A diferencia del polling, los webhooks son eficientes y casi en tiempo real. Sin embargo, como se basan en HTTP, debes manejar la seguridad y la confiabilidad de forma explícita.
Los casos de uso comunes incluyen notificaciones de pago, activadores de pipelines de CI/CD, notificaciones de chat y sincronización de datos entre aplicaciones SaaS.
Proteger webhooks con cargas firmadas
Los webhooks son endpoints de acceso público, por lo que los atacantes pueden enviar solicitudes falsas. Para evitarlo, los proveedores firman cada carga con una clave secreta. El receptor verifica la firma para garantizar la autenticidad e integridad.
Cómo funcionan las firmas HMAC
El método más común es HMAC-SHA256. El proveedor calcula un hash del cuerpo de la solicitud usando un secreto compartido y lo incluye en una cabecera (por ejemplo, X-Signature). El receptor vuelve a calcular el hash y lo compara.
// Ejemplo en Node.js: generar una firma
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// Enviar la firma en la cabecera: X-Signature: sha256=...
Verificar firmas en el receptor
Utiliza siempre una comparación en tiempo constante para prevenir ataques de temporización. En Node.js, usa crypto.timingSafeEqual.
// Ejemplo de middleware en Express.js
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // se necesita el cuerpo sin procesar
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
Importante: Utiliza el cuerpo de la solicitud sin procesar para la verificación, no el JSON parseado, para evitar discrepancias.
Medidas de seguridad adicionales
- Validación de marca de tiempo: Incluye una marca de tiempo en la firma y rechaza solicitudes con más de unos minutos de antigüedad para prevenir ataques de repetición.
- Solo HTTPS: Utiliza siempre endpoints HTTPS para proteger los datos en tránsito.
- Lista de IP permitidas: Si el proveedor publica rangos de IP, restringe las solicitudes entrantes a esas IPs.
Implementar reintentos confiables
Los webhooks pueden fallar debido a problemas de red, caídas del servidor o errores. Los proveedores suelen reintentar las entregas fallidas con retroceso exponencial. Como receptor, debes ser idempotente y manejar eventos duplicados.
Diseñar para la idempotencia
Cada evento de webhook debe tener un ID único. Almacena los IDs procesados para ignorar duplicados. Utiliza una base de datos con una restricción única o una caché como Redis.
// Pseudocódigo para procesamiento idempotente
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // TTL de 24h
Estrategias de reintento
Los proveedores suelen reintentar con retrasos crecientes (por ejemplo, 1s, 5s, 30s, 5m, 1h). Asegúrate de que tu endpoint responda rápidamente (en menos de 5 segundos) para evitar tiempos de espera. Si el procesamiento tarda más, confirma la recepción y procesa de forma asíncrona.
Aquí tienes una comparación de patrones de reintento comunes:
| Patrón | Ventajas | Desventajas |
|---|---|---|
| Intervalo fijo | Sencillo | Puede saturar un servidor que se está recuperando |
| Retroceso exponencial | Reduce la carga durante caídas | Entrega retrasada para errores transitorios |
| Retroceso exponencial con jitter | Previene el efecto estampida | Ligeramente más complejo |
Monitoreo y colas de mensajes muertos
Registra todos los intentos y fallos de webhooks. Después de un número máximo de reintentos, mueve los eventos a una cola de mensajes muertos (DLQ) para inspección manual. Configura alertas para tasas de fallo altas.
Poniéndolo todo junto: implementación paso a paso
- Configura un endpoint HTTPS que acepte solicitudes POST y lea el cuerpo sin procesar.
- Verifica la firma usando el secreto compartido y comparación en tiempo constante.
- Comprueba la marca de tiempo para prevenir ataques de repetición (si se proporciona).
- Asegura la idempotencia verificando el ID del evento contra una caché o base de datos.
- Procesa el evento de forma asíncrona si puede tardar; responde con 200 OK inmediatamente.
- Implementa lógica de reintento en el lado del emisor con retroceso exponencial y jitter.
- Monitorea y alerta sobre fallos, y usa una DLQ para errores persistentes.
Preguntas frecuentes
¿Qué es una carga de webhook firmada?
Una carga firmada incluye una firma criptográfica (generalmente HMAC) que permite al receptor verificar que la solicitud proviene de una fuente confiable y no fue manipulada.
¿Cómo manejo eventos de webhook duplicados?
Utiliza el ID de evento único proporcionado en la carga para rastrear los eventos procesados. Almacena los IDs en una base de datos o caché con un TTL para ignorar duplicados.
¿Qué debe devolver mi endpoint de webhook?
Devuelve un código de estado 2xx (por ejemplo, 200 OK) rápidamente para confirmar la recepción. Si el procesamiento falla, devuelve un 5xx para activar un reintento, pero solo para errores transitorios.
Al probar cargas de webhook, es posible que necesites inspeccionar estructuras JSON. Usa el Formateador JSON para validar y formatear las cargas de webhook para una depuración más sencilla.