Webhooks explicados: cargas firmadas y reintentos fiables
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:
- Usa el cuerpo raw. Parsea el JSON solo después de la verificación. Volver a serializar un objeto parseado cambia los espacios en blanco y el orden de las claves, por lo que la firma nunca coincidirá.
- Compara en tiempo constante. Una comparación de cadenas ingenua filtra información de temporización. Usa una función de comparación segura en tiempo.
- Incluye la marca de tiempo en la cadena firmada. Firmar
timestamp.bodyte permite rechazar solicitudes antiguas y bloquea ataques de replay.
// 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.
- Verifica la firma y la marca de tiempo.
- Inserta el evento en una tabla con una restricción única en el ID del evento.
- Devuelve
200inmediatamente. - 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
| Estado | Comportamiento del proveedor | Cuándo usarlo |
|---|---|---|
| 200 / 204 | Marcar como entregado | Evento aceptado (incluso si ya se procesó) |
| 400 | Normalmente sin reintento | Carga útil malformada que nunca podrás manejar |
| 401 | Normalmente sin reintento | Firma no coincide — revisa tu secreto |
| 429 | Reintento con retroceso | Estás aplicando límite de tasa |
| 500 / 503 | Reintento con retroceso | Fallo 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
- Usa solo HTTPS; nunca aceptes webhooks por HTTP simple.
- Guarda el secreto de firma en tu gestor de secretos y admite rotación — muchos proveedores permiten dos secretos activos.
- Registra el ID del evento, tipo, resultado de la firma y resultado del procesamiento para cada solicitud.
- Establece una ventana de tolerancia (cinco minutos es típico) para bloquear replays.
- Haz los manejadores idempotentes a nivel de base de datos, no solo en el código de la aplicación.
- Configura alertas cuando la tasa de fallos o el retraso de procesamiento supere un umbral.
- Proporciona un endpoint de replay manual para el personal de soporte.
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.