Webhooks explicados: payloads firmados y estrategias de reintento

Acabas de construir un endpoint de webhook para recibir eventos de un servicio de terceros. Todo funciona en las pruebas, pero en producción notas que algunos eventos nunca llegan o, peor aún, recibes eventos duplicados que causan inconsistencias en los datos. Estas son trampas clásicas de los webhooks que provienen de dos aspectos críticos: la autenticidad del payload y la confiabilidad de la entrega.

Los webhooks son callbacks HTTP disparados por eventos que envían datos a tu aplicación en tiempo real. A diferencia del polling, son eficientes y casi instantáneos. Pero introducen desafíos: ¿cómo sabes que la solicitud realmente provino del remitente esperado y cómo manejas los fallos cuando el receptor está temporalmente caído? Este artículo profundiza en los payloads firmados y los mecanismos de reintento, dándote patrones prácticos para construir integraciones de webhooks resilientes.

Por qué los webhooks necesitan firmas

Los endpoints de webhook son URLs públicamente accesibles. Sin verificación, cualquiera puede enviar solicitudes falsificadas a tu endpoint, potencialmente desencadenando acciones no autorizadas o corrupción de datos. Los payloads firmados resuelven esto añadiendo una firma criptográfica a cada solicitud, permitiéndote verificar la identidad del remitente y asegurar que el payload no ha sido manipulado.

La mayoría de los proveedores usan HMAC (Hash-based Message Authentication Code) con un secreto compartido. El remitente calcula un hash del payload usando el secreto y lo incluye en una cabecera. Tú recalculas el hash de tu lado y lo comparas. Si coinciden, la solicitud es legítima.

Implementando la verificación HMAC

Veamos una implementación típica en Node.js. Supongamos que el proveedor envía una firma en la cabecera X-Signature, calculada como HMAC-SHA256 del cuerpo crudo de la solicitud usando tu secreto.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Use raw body parser to preserve exact payload
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  const event = JSON.parse(req.body);
  // ... handle event
  
  res.status(200).send('OK');
});

Puntos clave:

• Usa siempre el cuerpo crudo de la solicitud para la verificación, no el JSON parseado. El parseo puede alterar espacios en blanco u orden de claves, rompiendo el hash.
• Usa una comparación segura contra ataques de temporización (timing-safe) para prevenir ataques de timing.
• Mantén tu secreto seguro; rótalo periódicamente y soporta múltiples secretos activos durante la rotación.

Diseñando una estrategia de reintento

Incluso con firmas, las entregas pueden fallar debido a problemas de red, caídas del servidor o timeouts. Una estrategia de reintento robusta asegura la entrega eventual sin saturar tu sistema ni al remitente.

1. Confirma rápido, procesa de forma asíncrona

Tu endpoint de webhook debería responder con un estado 2xx lo antes posible, idealmente en pocos segundos. Si el procesamiento tarda más, encola el evento para procesamiento en segundo plano. Esto previene timeouts y permite al remitente considerar la entrega exitosa.

2. Implementa backoff exponencial con jitter

Cuando una entrega falla (respuesta no 2xx o timeout), el remitente debería reintentar con retardos crecientes. El backoff exponencial (p. ej., 1s, 2s, 4s, 8s...) previene martillar tu endpoint. Añadir jitter aleatorio evita problemas de estampida (thundering herd) cuando muchos webhooks fallan simultáneamente.

Ejemplo de programación de reintentos:

• Intento 1: inmediato
• Intento 2: después de 30 segundos
• Intento 3: después de 2 minutos
• Intento 4: después de 10 minutos
• Intento 5: después de 1 hora

Después de un número máximo de reintentos (p. ej., 5), el remitente debería detenerse y notificarte (p. ej., vía email o dashboard).

3. Maneja duplicados con idempotencia

Los reintentos pueden causar entregas duplicadas. Tu endpoint debe ser idempotente: procesar el mismo evento múltiples veces debe tener el mismo efecto que procesarlo una vez. Usa un ID de evento único del payload y guárdalo. Antes de procesar, verifica si el ID ya ha sido visto; si es así, devuelve 200 sin reprocesar.

Enfoques comunes:

• Restricción única en base de datos sobre el ID de evento.
• Conjunto en Redis con TTL para IDs procesados recientemente.
• Claves de idempotencia en tu lógica de negocio.

Comparación: payloads firmados vs. otras medidas de seguridad

Las firmas HMAC son el estándar de facto porque son sin estado, eficientes y proporcionan una seguridad sólida cuando se implementan correctamente.

Buenas prácticas para consumidores de webhooks

• Valida las firmas en cada solicitud, incluso en desarrollo.
• Responde rápido; delega el procesamiento pesado a una cola.
• Registra todo—cabeceras, payload y resultado del procesamiento—para depuración.
• Monitorea los fallos y configura alertas para errores repetidos.
• Usa HTTPS para proteger los payloads en tránsito.
• Rota los secretos regularmente y soporta múltiples secretos activos durante la rotación.

Buenas prácticas para productores de webhooks

• Firma los payloads con un secreto único para cada consumidor.
• Incluye un ID de evento único para facilitar la idempotencia.
• Reintenta con backoff y limita los intentos.
• Proporciona un dashboard para que los consumidores vean los registros de entrega y reproduzcan eventos.
• Documenta tu esquema de firma claramente.

Probando tu implementación de webhooks

Usa herramientas como ngrok para exponer tu servidor local y simular entregas de webhooks. Escribe pruebas unitarias para la verificación de firmas y la lógica de idempotencia. Para pruebas de carga, considera herramientas que puedan enviar solicitudes firmadas a escala.

Al depurar, inspecciona el payload crudo y las cabeceras. Un formateador JSON puede ayudar a visualizar la estructura del payload. Prueba nuestro JSON Formatter para formatear y validar payloads de webhook rápidamente.

Preguntas frecuentes

¿Qué es un payload de webhook firmado?

Un payload firmado incluye una firma criptográfica (generalmente HMAC) que permite al receptor verificar la identidad del remitente y asegurar que el payload no ha sido alterado. Se calcula usando un secreto compartido y el cuerpo de la solicitud.

¿Cuántas veces debería reintentarse un webhook?

No hay un número universal, pero la práctica común es de 3 a 5 reintentos con backoff exponencial. Después de eso, el evento se considera fallido y el consumidor debería ser notificado para investigar o reproducir manualmente.

¿Puedo usar JWT en lugar de HMAC para las firmas de webhooks?

Sí, JWT puede funcionar, pero añade complejidad (emisión de tokens, expiración). HMAC es más simple y suficiente para la mayoría de los casos de uso. Elige según tu infraestructura y requisitos existentes.

¿Listo para inspeccionar y depurar payloads de webhooks? Usa nuestro JSON Formatter gratuito para formatear y validar JSON al instante.