Webhooks: Payloads firmados y estrategias de reintento

Backend2026-11-12TryQuickToolBox

Has construido una API que envía webhooks para notificar a servicios externos sobre eventos. Pero, ¿qué sucede cuando el endpoint receptor está caído? ¿O cuando un actor malicioso intenta falsificar una solicitud de webhook? Sin las protecciones adecuadas, tus webhooks pueden convertirse en una fuente de inconsistencias de datos y vulnerabilidades de seguridad. Este artículo explica cómo implementar payloads firmados y mecanismos de reintento para hacer tus webhooks confiables y seguros.

¿Qué son los webhooks y por qué necesitan seguridad?

Los webhooks son callbacks HTTP definidos por el usuario que se activan mediante eventos específicos. Permiten la comunicación en tiempo real entre sistemas, como notificar a un servicio de pagos cuando se realiza un pedido. Sin embargo, dado que los webhooks son endpoints de acceso público, son susceptibles a ataques de suplantación y repetición. Además, los problemas de red o la caída del receptor pueden provocar la pérdida de eventos. Por lo tanto, se deben abordar dos aspectos críticos: la autenticidad (mediante payloads firmados) y la confiabilidad (mediante reintentos).

Payloads firmados: garantizar autenticidad e integridad

Un payload firmado permite al receptor verificar que el webhook proviene de una fuente de confianza y que los datos no han sido alterados. Esto se logra normalmente mediante HMAC (Hash-based Message Authentication Code) con un secreto compartido.

Cómo funciona la firma HMAC

El emisor y el receptor comparten una clave secreta. Para cada solicitud de webhook, el emisor calcula una firma HMAC usando el secreto y el payload de la solicitud (a menudo incluyendo una marca de tiempo para prevenir ataques de repetición). La firma se envía en una cabecera, como X-Signature. El receptor recalcula la firma y la compara con la recibida. Si coinciden, la solicitud es auténtica.

Aquí tienes un ejemplo en Python usando HMAC-SHA256:

import hmac
import hashlib
import time

secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()

# Send headers: X-Signature: signature, X-Timestamp: timestamp

En el lado del receptor, verifica la firma y comprueba la marca de tiempo para asegurarte de que la solicitud es reciente (por ejemplo, dentro de 5 minutos). Esto previene los ataques de repetición.

Buenas prácticas para payloads firmados

Mecanismos de reintento: garantizar una entrega confiable

Incluso con payloads firmados, los fallos de red o los errores del receptor pueden provocar que la entrega del webhook falle. Una estrategia de reintento robusta asegura que los eventos se entreguen eventualmente sin saturar al receptor.

Diseñar una política de reintentos

Un enfoque común es el backoff exponencial con jitter. Por ejemplo, reintentar después de 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.

Ejemplo de programación de reintentos:

IntentoRetraso
1Inmediato
21 minuto
35 minutos
430 minutos
52 horas

Después de agotar los reintentos, mueve el evento a una cola de mensajes muertos para inspección manual.

Idempotencia: manejar entregas duplicadas

Debido a que los reintentos pueden causar entregas duplicadas, los receptores deben ser idempotentes. Incluye un ID de evento en el payload y haz que el receptor almacene los IDs procesados para ignorar duplicados. Alternativamente, diseña las operaciones para que sean naturalmente idempotentes (por ejemplo, usando PUT en lugar de POST).

Implementar webhooks: guía paso a paso

  1. Define los eventos y la estructura del payload: Documenta los eventos que emite tu sistema y el esquema JSON de cada uno.
  2. Genera un secreto: Crea un secreto único por endpoint de webhook y compártelo de forma segura.
  3. Firma cada solicitud: Calcula el HMAC sobre el payload y la marca de tiempo, e inclúyelo en las cabeceras.
  4. Implementa reintentos con backoff: Usa un sistema de colas para programar los reintentos.
  5. Proporciona una forma de verificar las firmas: Documenta el proceso de verificación para los receptores.
  6. Monitorea y registra: Rastrea los intentos de entrega y los fallos para la depuración.

Errores comunes y cómo evitarlos

Preguntas frecuentes

¿Qué es un payload de webhook firmado?

Un payload de webhook firmado incluye una firma criptográfica (por ejemplo, HMAC) que permite al receptor verificar la autenticidad del emisor y la integridad de los datos.

¿Cuántas veces debo reintentar un webhook fallido?

Normalmente de 3 a 5 reintentos con backoff exponencial. El número exacto depende de tu SLA y de la criticidad del evento.

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

Sí, se puede usar JWT, pero HMAC es más simple y común para la firma de webhooks. JWT añade sobrecarga y es más adecuado para tokens de autenticación.

¿Listo para probar tus payloads de webhooks? Usa nuestro formateador JSON para validar y embellecer tus payloads JSON antes de enviarlos.