Webhooks explicados: cargas firmadas y reintentos para integraciones fiables

Backend2026-11-13TryQuickToolBox

Acabas de crear un endpoint para recibir webhooks de un proveedor de pagos. La primera prueba funciona bien, pero en producción notas eventos faltantes, cargos duplicados y ninguna forma de saber si una solicitud es genuina. Los webhooks son simples en concepto pero complicados de hacer bien. Esta guía explica cómo proteger los webhooks con cargas firmadas e implementar una lógica de reintentos robusta para que tus integraciones no fallen silenciosamente.

¿Qué son los webhooks y por qué importan?

Los webhooks son callbacks HTTP definidos por el usuario que se activan por eventos. En lugar de que tu aplicación consulte una API en busca de cambios, el servicio envía datos a tu endpoint cuando algo sucede. Esto hace que las integraciones sean eficientes y casi en tiempo real.

Los casos de uso comunes incluyen notificaciones de pago (p. ej., Stripe), disparadores de CI/CD (p. ej., GitHub) y plataformas de mensajería (p. ej., Slack). Pero con este modelo de envío, pierdes el control sobre cuándo llegan las solicitudes. Por eso debes manejar explícitamente la seguridad y la fiabilidad.

El problema de seguridad: los webhooks sin firmar son peligrosos

Un webhook sin firmar es solo un POST HTTP a una URL pública. Cualquiera puede enviar una solicitud que parezca provenir de tu proveedor de pagos. Sin verificación, los atacantes podrían falsificar eventos, lo que llevaría a pedidos fraudulentos, filtraciones de datos o acciones no autorizadas.

La solución es firmar la carga. El emisor calcula una firma criptográfica sobre el cuerpo de la solicitud usando un secreto compartido y la incluye en una cabecera. Tu endpoint recalcula la firma y la compara. Si coinciden, sabes que la solicitud es auténtica y no ha sido manipulada.

Cómo firmar cargas de webhook con HMAC

HMAC (Hash-based Message Authentication Code) es el estándar para firmar webhooks. Utiliza una clave secreta y una función hash (como SHA-256) para producir una firma única para la carga y el secreto.

Así es como un emisor podría firmar una carga en Python:

import hmac
import hashlib
import json

secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature: 

En el lado receptor, debes verificar la firma antes de procesar la carga:

import hmac
import hashlib

def verify_signature(payload, received_signature, secret):
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

Importante: Utiliza siempre una función de comparación de tiempo constante como hmac.compare_digest para prevenir ataques de temporización. Además, verifica la firma contra el cuerpo raw de la solicitud, no contra una versión parseada, porque la serialización JSON puede diferir.

Mejores prácticas para cargas firmadas

Manejo de fallos: reintentos e idempotencia

Los webhooks pueden fallar: tu servidor podría estar caído, la red podría caerse o tu endpoint podría devolver un error. Un emisor fiable reintentará la entrega, pero debes diseñar tu receptor para manejar duplicados y eventos fuera de orden.

Estrategias de reintento

La mayoría de los proveedores de webhooks usan retroceso 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. Esto le da tiempo a tu sistema para recuperarse sin sobrecargarlo.

Si estás construyendo el lado del emisor, implementa una cola con reintentos programados. Almacena la carga y el número de intentos, y usa un worker para procesar los reintentos.

Idempotencia: la clave para reintentos seguros

Debido a que los reintentos pueden causar entregas duplicadas, tu endpoint debe ser idempotente. Esto significa que procesar el mismo evento varias veces debe tener el mismo efecto que procesarlo una vez.

Enfoques comunes:

Aquí hay una verificación de idempotencia simple en Python:

def process_event(event_id, payload):
    if db.exists('processed_events', event_id):
        return  # already processed
    # process payload
    db.insert('processed_events', event_id)

Asegúrate de que la verificación y el procesamiento ocurran en una sola transacción para evitar condiciones de carrera.

Comparación: polling vs. webhooks

AspectoPollingWebhooks
LatenciaDepende del intervalo (p. ej., 5 min)Casi en tiempo real
Carga del servidorSolicitudes constantes incluso sin cambiosSolicitudes solo en eventos
ComplejidadSimple de implementarRequiere firma, reintentos, idempotencia
FiabilidadTú controlas los reintentosDepende de la política de reintentos del emisor

Paso a paso: implementar un receptor de webhooks seguro

  1. Configura un endpoint HTTPS que acepte solicitudes POST y lea el cuerpo raw.
  2. Extrae la cabecera de firma (p. ej., X-Signature) y la cabecera de marca de tiempo si está presente.
  3. Verifica la firma usando HMAC y tu secreto. Rechaza si es inválida.
  4. Comprueba la marca de tiempo para prevenir ataques de repetición (p. ej., rechaza si es más antigua de 5 minutos).
  5. Parsea la carga y extrae el ID del evento.
  6. Verifica la idempotencia buscando el ID del evento en tu base de datos.
  7. Procesa el evento dentro de una transacción que también registre el ID del evento.
  8. Devuelve un estado 2xx rápidamente para acusar recibo. Si el procesamiento lleva tiempo, encola el trabajo y devuelve 202 Accepted.

Probar tu implementación de webhooks

Usa herramientas como ngrok para exponer tu servidor local y simular webhooks. Escribe pruebas unitarias para la verificación de firmas, idempotencia y lógica de reintentos. Por ejemplo, prueba que un ID de evento duplicado se ignora y que una firma inválida devuelve 401.

Al depurar, registra la carga y la firma recibidas (pero nunca registres secretos). Si trabajas con cargas JSON, un formateador JSON puede ayudarte a inspeccionar y validar la estructura rápidamente.

Preguntas frecuentes

¿Qué es una carga de webhook firmada?

Una carga firmada incluye una firma criptográfica (generalmente HMAC) calculada sobre el cuerpo de la solicitud con un secreto compartido. El receptor verifica la firma para asegurar que la solicitud es auténtica y no ha sido alterada.

¿Cuántas veces se debe reintentar un webhook?

No hay un número universal, pero la práctica común es de 3 a 5 reintentos con retroceso exponencial. Después de eso, el evento a menudo se marca como fallido y puede requerir intervención manual o una cola de mensajes no entregados.

¿Puedo usar webhooks sin HTTPS?

Nunca debes usar webhooks sobre HTTP simple. Sin TLS, los atacantes pueden interceptar la carga y la firma, y repetir o modificar solicitudes. Usa siempre HTTPS.

¿Listo para inspeccionar y formatear cargas de webhooks? Prueba nuestro formateador JSON gratuito para validar y embellecer datos JSON al instante.