Cómo diseñar webhooks de correo con entrega al menos una vez

El reto de entregar eventos de forma confiable

Para lograr una entrega al menos una vez (at-least-once) en los webhooks de correo, necesita un sistema en el que el emisor reintente las solicitudes fallidas con backoff exponencial y el receptor garantice la idempotencia. Como las redes no son confiables y los servidores fallan, no puede suponer que un único HTTP 200 OK garantice que el evento se procesó. La confiabilidad se consigue combinando una cola de reintentos persistente en el lado del emisor con una capa de deduplicación en el lado del receptor.

Cuando integra una API de correo como SendHQ, su aplicación necesita saber cuándo un correo se entregó, rebotó o se marcó como spam. Estos eventos son asíncronos. Si su endpoint de webhooks se cae durante cinco minutos en un pico de tráfico, podría perder miles de señales de entrega críticas. Eso crea un vacío en sus datos analíticos e impide que su sistema reaccione a los rebotes (algo esencial para mantener la reputación del remitente).

Anatomía de un webhook confiable

Una arquitectura de webhooks robusta se apoya en tres pilares: verificación de firmas, procesamiento idempotente y una estrategia de reintentos.

1. Verificación de firmas

Nunca confíe en una solicitud POST a su endpoint de webhooks basándose solo en la dirección IP o en la presencia de una clave de API en el cuerpo. Un atacante puede falsificar ambas cosas. En su lugar, use una firma HMAC (código de autenticación de mensajes basado en hash).

El emisor firma el payload con un secreto compartido y adjunta la firma en un encabezado (por ejemplo, X-SendHQ-Signature). El receptor vuelve a calcular el hash con el mismo secreto y lo compara con el encabezado.

const crypto = require('crypto'); function verifySignature(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); // Use timingSafeEqual to prevent timing attacks return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature)); }

2. Idempotencia y deduplicación

Entrega al menos una vez significa que el emisor seguirá enviando el evento hasta recibir una respuesta correcta. Si su servidor procesa el evento pero se cae antes de devolver el 200 OK, el emisor volverá a enviarlo. Sin idempotencia, podría contar una sola entrega como dos en su base de datos.

Cada evento debe tener un event_id único. Debería usar un patrón de clave de idempotencia para registrar los eventos ya procesados.

El flujo:

1. Reciba el payload del webhook.
2. Compruebe si el event_id existe en su tabla processed_events.
3. Si existe, devuelva 200 OK de inmediato e ignore el cuerpo.
4. Si no existe, procese el evento y registre el event_id en una única transacción.

3. La estrategia de reintentos

Desde el punto de vista del emisor, una política de reintentos es obligatoria. Un patrón habitual es el backoff exponencial con jitter. Por ejemplo: reintentar tras 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas.

Si el receptor devuelve un error 4xx (excepto 429), normalmente indica un error del cliente (como una firma incorrecta) y reintentar no servirá de nada. Un error 5xx o un tiempo de espera agotado indican un fallo transitorio en el que los reintentos son imprescindibles.

Ejemplo concreto de payload

Este es un payload típico de evento de entrega que podría recibir de SendHQ:

{ "event_id": "evt_12345abcde", "event_type": "delivered", "timestamp": "2026-09-15T10:00:00Z", "message_id": "msg_98765xyz", "recipient": "user@example.com", "metadata": { "order_id": "ord_5544" } }

Gestión de fallos y casos límite

El problema del "consumidor lento"

Si su manejador de webhooks realiza escrituras pesadas en la base de datos o llama a otras API externas de forma síncrona, su endpoint agotará el tiempo de espera. Esto activa la lógica de reintentos del emisor y provoca una "tormenta de reintentos" que puede tumbar su servidor.

La solución: desacoplar la recepción del procesamiento.

1. Reciba el webhook.
2. Verifique la firma.
3. Envíe el payload sin procesar a una cola de mensajes (como RabbitMQ, SQS o Redis).
4. Devuelva 200 OK de inmediato.
5. Un proceso worker independiente consume la cola y actualiza su base de datos.

El problema de la preparación de los agentes

Cuando los webhooks activan agentes de IA, aumenta el riesgo de bucles infinitos. Si un agente recibe un evento "delivered" y responde enviando otro correo, que a su vez genera otro evento "delivered", tiene un bucle.

Trate el envío de correo como un efecto secundario externo. Los agentes nunca deberían enviar correos automáticamente a partir de un webhook sin una aprobación humana (human-in-the-loop) o una comprobación estricta de máquina de estados que confirme que la acción es necesaria.

Comparativa del ecosistema

Al elegir un proveedor, la confiabilidad suele depender de cómo gestiona estos eventos y de cuánto cobra por el volumen de correo que los genera.

Para el correo transaccional de alto volumen, la diferencia de costo es enorme. Según los precios de Amazon SES, el envío a la carta cuesta 0.10 USD por cada 1.000 correos. En cambio, los precios de Postmark empiezan en 15 USD al mes por 10.000 correos, con excedentes de entre 1.20 y 1.80 USD por cada 1.000. Para un volumen de 50.000 correos, SES a la carta cuesta unos 5 USD, mientras que con los planes de Postmark costaría aproximadamente 66 USD.

Otras opciones son Resend, que ofrece un plan gratuito de 3.000 correos al mes (con un máximo de 100 al día) y un plan Pro de 20 USD al mes por 50.000 correos. Mailgun empieza en 15 USD al mes por 10.000 correos. SendGrid ha convertido su plan gratuito en una prueba de 60 días, y Essentials empieza en 19.95 USD al mes.

Sea cual sea el proveedor, lo que determina la integridad de sus datos es la confiabilidad con la que usted consume estos eventos.

Lista de comprobación de implementación para ingenieros

• Verificación de firma: ¿El payload se verifica mediante un secreto compartido y una función de comparación en tiempo constante?
• Procesamiento asíncrono: ¿El endpoint devuelve 200 OK antes de ejecutar lógica de negocio pesada?
• Idempotencia: ¿Existe una restricción de unicidad sobre event_id para evitar el procesamiento duplicado?
• Gestión de tiempo de espera: ¿El tiempo de espera se establece por debajo del tiempo de espera del proveedor para evitar reintentos superpuestos?
• Monitoreo: ¿Tiene alertas para un aumento repentino de respuestas 5xx en el endpoint de su webhook?
• Estado de DNS: ¿Sus servidores de recepción están configurados correctamente? Use herramientas como el verificador de DNS de correo de SendHQ para asegurarse de que su infraestructura sea accesible y esté configurada correctamente.
• Estándares de autenticación: ¿Ha implementado DKIM, SPF y DMARC para asegurar que se acepte su correo saliente y reducir así el número de webhooks de «rebote» que debe gestionar?

Resumen de las concesiones

Enfoque | Ventajas | Desventajas

Procesamiento síncrono | Fácil de implementar, consistencia inmediata | Alto riesgo de tiempos de espera agotados, propenso a tormentas de reintentos

Procesamiento basado en colas | Muy escalable, resistente a los picos | Mayor complejidad de infraestructura, consistencia eventual

Registro simple | Poca sobrecarga | Sin forma de recuperar eventos perdidos sin registros manuales

Tabla de idempotencia | Integridad de datos garantizada | Una escritura adicional en la base de datos por evento

Conclusiones

La confiabilidad de los webhooks de correo no consiste en evitar los fallos, sino en diseñar para ellos. Si parte de que la red fallará y de que los eventos se entregarán más de una vez, construirá un sistema realmente resiliente. Tanto si gestiona los registros SPF de un proyecto pequeño como si escala un sistema transaccional masivo, la verificación de firmas y la idempotencia siguen siendo los patrones de referencia.

Construya su infraestructura de correo con SendHQ.