Webhooks explicados: payloads firmados y reintentos fiables

Backend2026-11-17TryQuickToolBox

Acabas de integrar un servicio de terceros que envía webhooks a tu endpoint. Todo funciona en las pruebas, pero en producción notas eventos perdidos, entregas duplicadas e incluso solicitudes falsificadas. Los webhooks son simples en concepto pero complicados de implementar bien. Este artículo explica cómo proteger los webhooks con payloads firmados e implementar una lógica de reintentos fiable para que tus integraciones sean robustas y confiables.

Qué son los webhooks y por qué importan

Los webhooks son callbacks HTTP definidos por el usuario que se activan mediante eventos. En lugar de consultar una API periódicamente para detectar cambios, registras una URL y el servicio envía una solicitud POST con los datos del evento cada vez que ocurre algo. Este modelo push reduce la latencia y la carga del servidor, lo que lo hace ideal para integraciones en tiempo real como notificaciones de pago, disparadores de CI/CD y mensajes de chat.

Sin embargo, los webhooks introducen desafíos: verificar la autenticidad, gestionar fallos y garantizar el procesamiento exactamente una vez. Abordémoslos uno por uno.

Proteger webhooks con payloads firmados

Sin verificación, cualquiera puede enviar solicitudes falsas a tu endpoint de webhook. Los payloads firmados lo resuelven incluyendo una firma criptográfica en las cabeceras de la solicitud, generada mediante un secreto compartido. Verificas la firma para confirmar que la solicitud proviene del remitente esperado y que no ha sido manipulada.

Cómo funcionan las firmas HMAC

La mayoría de los servicios usan HMAC (Hash-based Message Authentication Code) con SHA-256. El remitente calcula un hash del cuerpo de la solicitud (y a veces de una marca de tiempo) usando el secreto, y lo incluye en una cabecera como X-Signature. Tú recalculas el hash en tu lado y lo comparas.

Aquí tienes un flujo de verificación típico en Node.js:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Usa siempre una comparación de tiempo constante para prevenir ataques de temporización. Además, incluye una marca de tiempo en los datos firmados y rechaza solicitudes con más de unos minutos de antigüedad para prevenir ataques de repetición.

Buenas prácticas para la verificación de firmas

Implementar reintentos fiables

Las redes fallan, los servidores se reinician y los endpoints se agotan por timeout. Un sistema de webhooks robusto debe reintentar las entregas fallidas. Pero los reintentos pueden causar duplicados, así que necesitas idempotencia.

Estrategias de reintento

La mayoría de los proveedores usan backoff exponencial con jitter. Por ejemplo, reintentar tras 1 minuto, luego 5 minutos, luego 30 minutos, hasta un número máximo de intentos (por ejemplo, 5). Incluye un ID de evento único en el payload para que el receptor pueda deduplicar.

En el lado receptor, responde rápidamente con un estado 2xx para confirmar la recepción, y luego procesa de forma asíncrona. Si el procesamiento falla, no puedes confiar en que el remitente reintente indefinidamente: implementa tu propia cola de mensajes muertos o alertas.

Claves de idempotencia

Para gestionar entregas duplicadas, usa una clave de idempotencia (a menudo el ID del evento) y almacena los IDs procesados durante un periodo razonable. Antes de procesar, comprueba si el ID ya ha sido visto; si es así, devuelve éxito sin volver a procesar.

// Ejemplo: comprobación de idempotencia en Express
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  await db.seenEvents.add(eventId);
  // procesar el evento de forma asíncrona
  res.status(200).send('OK');
});

Comparación: polling vs webhooks

AspectoPollingWebhooks
LatenciaAlta (basada en intervalos)Baja (casi en tiempo real)
Carga del servidorAlta (solicitudes frecuentes)Baja (basada en eventos)
ComplejidadSencilla de implementarRequiere verificación de firma y reintentos
FiabilidadDepende de la frecuencia de pollingDepende del mecanismo de reintento

Paso a paso: construir un receptor de webhooks seguro

  1. Configura un endpoint que acepte solicitudes POST sobre HTTPS.
  2. Verifica la firma usando el secreto compartido y rechaza solicitudes inválidas con 401.
  3. Comprueba la marca de tiempo para prevenir ataques de repetición.
  4. Responde inmediatamente con 200 OK tras la validación básica, y luego procesa de forma asíncrona.
  5. Implementa idempotencia usando los IDs de evento para evitar el procesamiento duplicado.
  6. Registra y monitoriza los fallos y reintentos.

Preguntas frecuentes

¿Qué es un payload de webhook firmado?

Un payload firmado incluye una firma criptográfica (normalmente HMAC) que permite al receptor verificar la autenticidad e integridad de la solicitud usando un secreto compartido.

¿Cuántas veces debo reintentar un webhook fallido?

La práctica común es de 3 a 5 reintentos con backoff exponencial. Después de eso, mueve el evento a una cola de mensajes muertos para inspección manual.

¿Puedo usar webhooks sin HTTPS?

No, HTTPS es esencial para proteger el payload y la firma de escuchas y manipulaciones. Usa siempre TLS.

¿Listo para probar tus payloads de webhook? Usa nuestro formateador JSON para imprimir y validar payloads JSON rápidamente.