Webhooks explicados: cargas firmadas y reintentos fiables

Backend2026-11-11TryQuickToolBox

Implementas una integración de pagos y todo funciona en staging. Luego, en producción, un cliente paga, tu endpoint se queda sin responder durante dos segundos y el pedido nunca se activa. Mientras tanto, el proveedor de pagos reintenta el mismo evento tres veces y tu aplicación crea tres pedidos duplicados para el que sí se completó. Los webhooks parecen simples — solo un POST HTTP — pero lo difícil es la confianza y las garantías de entrega.

Este artículo cubre las dos cosas que más a menudo rompen las integraciones de webhooks: verificar que una solicitud realmente proviene del emisor y manejar los reintentos sin duplicar efectos secundarios.

Qué es realmente un webhook

Un webhook es una llamada API inversa. En lugar de que tu servidor consulte al proveedor cada minuto preguntando «¿hay algo nuevo?», el proveedor envía una solicitud HTTP a una URL que registraste cuando ocurre un evento. La carga útil suele ser JSON y el tipo de evento está en el cuerpo o en una cabecera.

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

Hay dos decisiones de diseño que importan en el lado del emisor y que deberías comprobar al evaluar cualquier proveedor: ¿firma la carga útil? y ¿reintenta en caso de fallo?

Por qué los webhooks sin firmar son peligrosos

La URL de tu webhook es pública. Cualquiera que la descubra puede enviar un evento falso de payment.succeeded y marcar un pedido impago como pagado. Una lista de IPs permitidas ayuda un poco, pero los proveedores cambian de IP, operan detrás de CDNs y puede que no obtengas una lista estable.

La solución robusta es una firma HMAC sobre el cuerpo raw de la solicitud usando un secreto compartido que solo tú y el proveedor conocéis. El proveedor calcula la firma y la envía en una cabecera; tú la recalculas y comparas.

Verificar una firma correctamente

Tres detalles son fáciles de equivocar:

// Ejemplo con Node.js / Express
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Rechazar solicitudes obsoletas (protección contra replay)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... manejar evento
  res.status(200).send('ok');
});

Fíjate en el middleware express.raw(). Si montas express.json() antes de esta ruta, el cuerpo ya está parseado y la verificación de la firma falla silenciosamente — un error muy común.

Diseñar reintentos que no pierdan eventos

La entrega de webhooks es al-menos-una-vez, no exactamente-una-vez. Las redes fallan, tu despliegue reinicia un contenedor y el proveedor no tiene idea de si tu respuesta 200 fue real. Por eso el proveedor reintenta con retroceso exponencial, a menudo durante horas o días.

Responde rápido, procesa después

Tu endpoint debe hacer lo mínimo: verificar, persistir el evento raw, devolver 2xx. El trabajo pesado — enviar correos, llamar a otras APIs, generar facturas — debe ocurrir en un trabajo en segundo plano. Si el procesamiento tarda más que el timeout del proveedor, la solicitud se trata como fallida y se reintenta aunque ya hayas hecho el trabajo.

  1. Verifica la firma y la marca de tiempo.
  2. Inserta el evento en una tabla con una restricción única en el ID del evento.
  3. Devuelve 200 inmediatamente.
  4. Procesa el evento almacenado de forma asíncrona, marcándolo como completado.

Idempotencia: la solución real para los duplicados

Como ocurren reintentos, tu manejador debe ser seguro de ejecutar dos veces. El ID del evento es la clave de idempotencia natural.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

Si la inserción afecta a cero filas, ya has visto este evento antes — confírmalo y continúa. Para la lógica de negocio, aplica la misma idea: usa el ID del pedido como clave única al activar un pago, para que un segundo evento no pueda crear una segunda activación.

Elegir códigos de estado intencionadamente

EstadoComportamiento del proveedorCuándo usarlo
200 / 204Marcar como entregadoEvento aceptado (incluso si ya se procesó)
400Normalmente sin reintentoCarga útil malformada que nunca podrás manejar
401Normalmente sin reintentoFirma no coincide — revisa tu secreto
429Reintento con retrocesoEstás aplicando límite de tasa
500 / 503Reintento con retrocesoFallo temporal, base de datos caída, despliegue en curso

Devolver 200 para un evento que no pudiste almacenar es la peor opción: el proveedor deja de reintentar y el evento se pierde para siempre. Devuelve un 5xx y deja que el reintento haga su trabajo.

Lista de verificación práctica para producción

Probar webhooks en local

No puedes recibir fácilmente un POST público en localhost. Opciones: una herramienta de túnel que exponga tu puerto de desarrollo, la CLI del proveedor si la tiene, o un pequeño script que envíe una carga firmada a tu manejador para que puedas ejercitar la ruta de verificación.

La prueba más valiosa es el duplicado: envía el mismo evento dos veces y confirma que tu sistema termina en el mismo estado. Luego envía un evento con una marca de tiempo antigua y confirma que se rechaza. Después altera un byte del cuerpo y confirma que la verificación de firma falla.

Depurar cargas útiles

Los cuerpos de los webhooks son JSON, y las cargas malformadas o muy anidadas son dolorosas de leer en los registros. Un formateador te ayuda a inspeccionar la estructura rápidamente antes de escribir código de parseo. El formateador JSON se ejecuta en el navegador, así que puedes pegar una carga capturada sin enviar datos de clientes a un servidor.

Preguntas frecuentes

¿Cuál es la diferencia entre un webhook y una API?

Una API es pull: tu código llama al proveedor cuando necesita datos. Un webhook es push: el proveedor llama a tu endpoint cuando ocurre un evento. La mayoría de las integraciones usan ambos — webhooks para notificaciones de eventos y la API para obtener detalles completos o realizar acciones.

¿Por qué mi firma HMAC nunca coincide?

La causa habitual es firmar un cuerpo re-serializado en lugar de los bytes raw. Los espacios en blanco, el orden de las claves y el escape de unicode cambian el hash. Lee el cuerpo raw de la solicitud antes de cualquier middleware JSON y confirma que el secreto y el algoritmo de hash coinciden con la documentación del proveedor.

¿Están garantizados los reintentos de webhooks?

No. Los proveedores suelen reintentar durante una ventana limitada con retroceso exponencial y luego desisten. Trata los webhooks como un canal de notificación rápida en lugar de una fuente de verdad: reconcilia periódicamente contra la API del proveedor para que los eventos perdidos se corrijan eventualmente.

Si hoy estás construyendo o depurando un receptor de webhooks, empieza por asegurar la verificación de firmas y el almacenamiento idempotente — esos dos cambios eliminan la mayoría de los incidentes reales con webhooks.