Webhooks explicados: cargas firmadas y reintentos

Backend2026-11-16TryQuickToolBox

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

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ónVentajasDesventajas
Intervalo fijoSencilloPuede saturar un servidor que se está recuperando
Retroceso exponencialReduce la carga durante caídasEntrega retrasada para errores transitorios
Retroceso exponencial con jitterPreviene el efecto estampidaLigeramente 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

  1. Configura un endpoint HTTPS que acepte solicitudes POST y lea el cuerpo sin procesar.
  2. Verifica la firma usando el secreto compartido y comparación en tiempo constante.
  3. Comprueba la marca de tiempo para prevenir ataques de repetición (si se proporciona).
  4. Asegura la idempotencia verificando el ID del evento contra una caché o base de datos.
  5. Procesa el evento de forma asíncrona si puede tardar; responde con 200 OK inmediatamente.
  6. Implementa lógica de reintento en el lado del emisor con retroceso exponencial y jitter.
  7. 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.