Webhooks Explicados: Payloads Firmados y Reintentos
Has construido una API y ahora necesitas notificar a otros servicios cuando ocurren eventos. El polling es ineficiente, así que implementas webhooks. Pero pronto te das cuenta: ¿cómo aseguras que el payload es auténtico? ¿Qué pasa si el receptor está caído? Sin las protecciones adecuadas, los webhooks pueden convertirse en un agujero de seguridad y una pesadilla de fiabilidad.
En este artículo, repasaremos los fundamentos de los webhooks, centrándonos en dos aspectos críticos: los payloads firmados para la seguridad y los mecanismos de reintento para la fiabilidad. Proporcionaremos ejemplos de código prácticos y buenas prácticas para ayudarte a construir sistemas de webhooks robustos.
¿Qué son los Webhooks?
Los webhooks son callbacks HTTP definidos por el usuario. Permiten que un sistema envíe datos en tiempo real a otro cuando ocurre un evento específico. A diferencia de las APIs donde tú extraes los datos, los webhooks te envían los datos. Esto los hace ideales para arquitecturas orientadas a eventos.
Los casos de uso comunes incluyen notificaciones de pago (por ejemplo, Stripe), disparadores de CI/CD (por ejemplo, GitHub) y plataformas de mensajería (por ejemplo, Slack). El emisor realiza una petición HTTP POST a una URL proporcionada por el receptor, con un payload que contiene los detalles del evento.
¿Por qué proteger los Webhooks con Payloads Firmados?
Los endpoints de webhook son accesibles públicamente, lo que los hace vulnerables a la suplantación. Un atacante podría enviar payloads falsos para desencadenar acciones no deseadas. Para prevenirlo, los emisores firman el payload usando un secreto compartido. El receptor verifica la firma para asegurar la autenticidad e integridad.
La firma normalmente implica generar un HMAC (Hash-based Message Authentication Code) del payload usando una clave secreta. La firma se envía en una cabecera (por ejemplo, X-Signature). El receptor recalcula el HMAC y lo compara con la firma recibida.
Cómo Implementar Payloads Firmados
Veamos un ejemplo sencillo en Python usando Flask. El emisor calcula la firma:
import hmac
import hashlib
import json
import requests
secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)
El receptor verifica la firma:
from flask import Flask, request, abort
import hmac
import hashlib
app = Flask(__name__)
secret = b'your_shared_secret'
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
body = request.get_data()
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
# Process payload
return '', 200
Buenas prácticas:
- Usa un secreto fuerte y rótalo periódicamente.
- Incluye una marca de tiempo en los datos firmados para prevenir ataques de replay.
- Usa
hmac.compare_digestpara una comparación en tiempo constante. - Firma el cuerpo sin procesar, no el JSON parseado, para evitar inconsistencias.
Implementando Reintentos Confiables
La entrega de webhooks puede fallar debido a problemas de red, caídas del receptor o errores de procesamiento. Un sistema robusto debería reintentar las entregas fallidas con backoff exponencial.
Estrategia de Reintentos
Enfoque común: reintentar hasta N veces con retardos crecientes (por ejemplo, 1s, 5s, 30s, 5m, 30m). Tras agotar los reintentos, marca la entrega como fallida y alerta.
Aquí tienes un mecanismo de reintento sencillo en Python usando la librería requests y tenacity:
from tenacity import retry, stop_after_attempt, wait_exponential
import requests
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
headers = {'X-Signature': signature}
response = requests.post(url, json=payload, headers=headers, timeout=10)
response.raise_for_status()
return response
Buenas prácticas para reintentos:
- Usa claves de idempotencia para permitir a los receptores deduplicar.
- Establece un timeout para cada petición para evitar bloqueos.
- Registra cada intento para depuración.
- Proporciona una forma de reintentar manualmente desde un panel.
Comparación: Payloads Firmados vs. Basic Auth
| Enfoque | Seguridad | Complejidad | Protección contra Replay |
|---|---|---|---|
| Basic Auth | Baja (credenciales enviadas cada vez) | Baja | No |
| Payload Firmado (HMAC) | Alta | Media | Sí (con marca de tiempo) |
Paso a Paso: Construir un Emisor de Webhooks con Reintentos
- Define el payload del evento e incluye un ID de evento único y una marca de tiempo.
- Calcula la firma usando HMAC-SHA256 sobre el cuerpo sin procesar.
- Envía la petición con la firma en una cabecera.
- Maneja los fallos reintentando con backoff exponencial.
- Registra las entregas y proporciona visibilidad.
Probar Webhooks
Usa herramientas como ngrok para exponer tu servidor local y probar la entrega de webhooks. Verifica siempre las firmas en tus pruebas para detectar problemas a tiempo.
Preguntas Frecuentes
¿Qué es un payload firmado en webhooks?
Un payload firmado es una petición de webhook donde el emisor incluye una firma criptográfica (normalmente HMAC) generada con un secreto compartido. El receptor verifica la firma para confirmar que la petición es auténtica y no ha sido manipulada.
¿Cuántas veces debo reintentar un webhook fallido?
No hay un número fijo, pero la práctica común es de 3 a 5 reintentos con backoff exponencial. Considera el tiempo de inactividad típico de tu receptor y la criticidad del evento. Permite siempre reintentos manuales.
¿Puedo usar JWT para firmas de webhooks?
Sí, se puede usar JWT, pero es más complejo. Las firmas HMAC son más simples y suficientes para la mayoría de los casos. Si necesitas incluir claims, JWT podría ser adecuado.
¿Listo para probar tus payloads de webhook? Usa nuestro JSON Formatter para validar y formatear tus payloads JSON antes de enviarlos.