Webhooks explicados: payloads firmados y reintentos

Backend2026-11-15TryQuickToolBox

Por qué los webhooks fallan en producción

Has construido un endpoint de webhook, lo has probado localmente y todo funciona. Luego llega producción: un proveedor envía un evento duplicado, tu endpoint se agota, o un atacante falsifica una solicitud. De repente, tu integración es poco confiable e insegura.

Los webhooks son simples en concepto—callbacks HTTP activados por eventos—pero las implementaciones de nivel producción requieren un manejo cuidadoso de la seguridad y la confiabilidad. Esta guía cubre dos aspectos críticos: payloads firmados para verificar la autenticidad y estrategias de reintento para manejar fallos.

¿Qué son los webhooks?

Un webhook es un callback HTTP definido por el usuario. Cuando ocurre un evento en un sistema de origen (por ejemplo, un pago exitoso), envía una solicitud HTTP POST a una URL que proporcionas, conteniendo datos sobre el evento. Este modelo push es más eficiente que el polling.

Pero los webhooks introducen desafíos:

Abordemos primero la seguridad.

Asegurando webhooks con payloads firmados

Los payloads firmados usan un secreto compartido para crear una firma criptográfica del cuerpo de la solicitud. El remitente incluye esta firma en un encabezado (por ejemplo, X-Signature). Tu endpoint recalcula la firma y la compara. Si coinciden, la solicitud es auténtica.

Cómo funciona la firma HMAC

La mayoría de los proveedores usan HMAC-SHA256. La firma se calcula sobre el cuerpo crudo de la solicitud usando el secreto compartido. Aquí está el flujo:

  1. El proveedor y el consumidor comparten una clave secreta.
  2. El proveedor crea el payload, calcula HMAC-SHA256(secreto, payload) y lo envía en un encabezado.
  3. El consumidor recibe la solicitud, lee el cuerpo crudo, calcula el mismo HMAC y lo compara.

Importante: Usa el cuerpo crudo exactamente como se recibió—parsear y re-serializar JSON puede cambiar los bytes y romper la firma.

Implementando la verificación de firma

Aquí tienes un ejemplo en Node.js usando Express:

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

// Usa el parser de cuerpo crudo para rutas de webhook
app.post('/webhook', express.raw({ type: 'application/json' }), (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');
  }
  
  // Procesa el evento
  const event = JSON.parse(req.body);
  // ... manejar evento
  
  res.status(200).send('OK');
});

Siempre usa una comparación de tiempo constante como crypto.timingSafeEqual para prevenir ataques de temporización.

Otras consideraciones de seguridad

Implementando reintentos confiables

Incluso con un endpoint seguro, problemas de red o fallos temporales pueden causar que la entrega del webhook falle. Un mecanismo de reintento robusto asegura que los eventos no se pierdan.

Estrategia de reintento del lado del remitente

Si estás construyendo un remitente de webhooks, implementa retroceso exponencial con jitter. Por ejemplo:

Añade jitter aleatorio para evitar problemas de estampida. Detente después de un número máximo de intentos y alerta.

Mejores prácticas del lado del receptor

Como consumidor de webhooks, no puedes controlar la política de reintentos del remitente, pero puedes hacer tu endpoint resiliente:

Manejando duplicados con idempotencia

Los proveedores de webhooks a menudo reintentan en timeouts, por lo que puedes recibir el mismo evento varias veces. Haz que tu procesamiento sea idempotente:

Ejemplo usando un índice único de base de datos:

async function handleEvent(event) {
  try {
    await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
  } catch (err) {
    if (err.code === '23505') { // violación de unicidad
      return; // ya procesado
    }
    throw err;
  }
  // procesar evento
}

Comparación: Enfoques de seguridad para webhooks

Enfoque Pros Contras
Firma HMAC Integridad fuerte, ampliamente soportada Requiere gestión de secretos
Basic Auth Simple Menos seguro, credenciales en el encabezado
Lista de IPs permitidas Fácil de implementar Las IPs pueden cambiar, no es robusto

Las firmas HMAC son el estándar de facto para la seguridad de webhooks.

Probando webhooks localmente

Herramientas como ngrok o localtunnel exponen tu servidor local a Internet para pruebas. Siempre prueba la verificación de firma y la lógica de reintentos con fallos simulados.

Al inspeccionar payloads JSON de webhooks, formatearlos puede ayudar a depurar. Prueba nuestro JSON Formatter para imprimir y validar payloads de webhooks.

Preguntas frecuentes

¿Cómo verifico una firma de webhook?

Calcula un HMAC del cuerpo crudo de la solicitud usando el secreto compartido, luego compáralo con el encabezado de firma usando una función de comparación de tiempo constante.

¿Qué debo hacer si mi endpoint de webhook está caído?

La mayoría de los proveedores reintentan con retroceso exponencial. Asegúrate de que tu endpoint devuelva un 2xx rápidamente y procesa de forma asíncrona para minimizar el impacto del tiempo de inactividad.

¿Puedo usar webhooks sin firmas?

Es riesgoso. Sin firmas, los atacantes pueden falsificar solicitudes. Siempre usa payloads firmados o al menos autenticación básica sobre HTTPS.

Conclusión

Los webhooks son poderosos pero requieren atención a la seguridad y la confiabilidad. Implementa la verificación de firma HMAC para asegurar la autenticidad, y diseña tu sistema para manejar reintentos y duplicados con elegancia. Con estas prácticas, tus integraciones de webhooks serán robustas y estarán listas para producción.