We Manegit
Resumen ejecutivo
En aplicaciones web, plataformas SaaS y tiendas online, dar por sentado que la llamada a la función de envío de correo (sendEmail()) garantiza que el mensaje llegue es un error de arquitectura grave. El envío por SMTP o por API funciona como una caja negra asíncrona: tu servidor le entrega el mensaje al proveedor de envío, pero no sabe si el usuario lo recibió, si fue rechazado o si cayó en la carpeta de correo no deseado. Los webhooks de eventos de correo le permiten a tu equipo técnico escuchar la respuesta de los servidores receptores (como Gmail o Microsoft 365) y automatizar decisiones en la base de datos: avisarle al usuario que escribió mal su correo, dejar de enviar a casillas inexistentes y medir cuánto tarda en llegar un código OTP o una factura. Con Row, tu Relay Owner conecta tu sistema con el proveedor de envíos, deja los webhooks configurados y monitorea que los correos lleguen.
1. De la "caja negra" SMTP al monitoreo por eventos: Por qué la API de correo no es suficiente
Cuando un usuario pide restablecer su contraseña en una plataforma, la aplicación hace una petición HTTP POST a la API de correo o abre una conexión SMTP. Si la API responde 200 OK o el servidor SMTP contesta 250 Message Accepted, la aplicación suele dar el proceso por terminado y muestra en pantalla: "Te enviamos un correo con instrucciones".
Pero esa confirmación solo significa que el servidor de envío aceptó el mensaje en su cola de salida. No garantiza que haya llegado a la bandeja de entrada del destinatario.
Entre esa aceptación y la llegada a la bandeja ocurren varias etapas técnicas:
- El servidor de envío consulta los registros DNS MX del dominio del destinatario.
- Establece una conexión TLS segura con los servidores de Google, Microsoft, Yahoo o el servidor privado de la empresa destinataria.
- Pasa por los filtros de reputación, la alineación DMARC y las listas de bloqueo.
Si el servidor de destino rechaza el mensaje porque la casilla está llena, porque no existe o porque aplicó una restricción temporal de velocidad (rate limiting), tu aplicación no se entera si no tiene webhooks activos. El usuario espera en vano su código de acceso, la venta se cae y tu equipo de soporte pierde horas buscando en registros del servidor sin saber qué pasó.
2. Glosario de telemetría web: Webhook, Event Payload, Signature Verification y Latencia SMTP
Para armar el seguimiento de los correos transaccionales, tu equipo de desarrollo necesita manejar estos conceptos:
- Webhook (HTTP Callback)
- Un mecanismo por el cual el proveedor de envío manda automáticamente un paquete de datos en formato JSON a una URL pública de tu aplicación en el momento en que pasa algo con un mensaje.
- Event Payload
- La estructura JSON con la información del evento: identificador único del mensaje (Message-ID), destinatario, tipo de evento, código de respuesta SMTP del servidor receptor, marca de tiempo UNIX y metadatos propios.
- Firma del webhook (HMAC Signature)
- Un encabezado criptográfico que viaja con el payload y le permite a tu backend verificar que la notificación la emitió tu proveedor de envío y que nadie la falsificó o alteró en el camino.
- Idempotencia
- La propiedad de un procesador de eventos por la cual recibir dos veces el mismo paquete no cambia el resultado en la base de datos ni repite acciones en el sistema.
- Latencia de evento (Event Delivery Time)
- El tiempo que pasa desde que ocurre el evento en el servidor de destino (por ejemplo, la entrega en Gmail) hasta que tu backend procesa el webhook. Medirla ayuda a detectar demoras.
3. Los 6 eventos críticos que tu equipo de desarrollo debe escuchar por Webhook
Una arquitectura profesional de notificaciones transaccionales no se queda con métricas globales: sigue cada mensaje a través de seis eventos principales. Los nombres exactos cambian según el proveedor de envío, pero la lógica es la misma:
1. Event: Processed / Queued (aceptado en la cola de salida)
Se dispara cuando el proveedor de envío valida el mensaje, comprueba la autenticación de la solicitud a la API y lo pone en la cola de salida.
Acción en tu sistema: registrar el identificador único del mensaje (message_id) en tu tabla de auditoría y cambiar el estado del correo de PENDING a PROCESSED. Es la confirmación de que el mensaje salió de tu infraestructura.
2. Event: Delivered (confirmación de recepción por el servidor de destino)
El evento central de la entregabilidad. Se emite cuando el servidor del destinatario (por ejemplo, mx1.google.com) responde con un código de éxito 250 2.0.0 OK y acepta el mensaje. Que el servidor lo acepte no asegura que vaya a la bandeja principal: todavía puede terminar en spam.
Acción en tu sistema: marcar la notificación como DELIVERED. En sistemas de alta seguridad o de firma de contratos, este evento sirve como constancia de entrega en auditorías internas.
3. Event: Deferred (retraso temporal en la cola / Rate Limiting)
Ocurre cuando el servidor receptor no rechaza el correo pero pide postergar la entrega (código SMTP 4xx), por lo general porque la casilla está llena o porque está aplicando límites de velocidad temporales.
Acción en tu sistema: marcar la notificación como DEFERRED_RETRYING. No hace falta avisarle al usuario de un fallo: el proveedor de envío reintenta la entrega automáticamente, con pausas entre intentos.
4. Event: Bounce (rechazo duro 5xx o blando 4xx agotado)
Se activa cuando el servidor de destino rechaza el mensaje de forma definitiva (código SMTP 5xx) porque la casilla no existe, el dominio no es válido o la IP de envío está bloqueada, o cuando se agotan los reintentos de un rechazo temporal.
Acción en tu sistema: agregar de inmediato la casilla a tu lista de supresión y marcar el campo del usuario como EMAIL_INVALID. Si el usuario está usando la plataforma en ese momento, la interfaz debería mostrarle un aviso: "No pudimos entregar tu correo; revisa la dirección que ingresaste".
5. Event: Spam Report (queja manual de correo no deseado)
Se dispara cuando un usuario marca el mensaje como spam en su cliente de correo y el proveedor de buzones (por ejemplo, Yahoo o Outlook) se lo informa a tu proveedor de envío mediante los circuitos de quejas (Feedback Loops).
Acción en tu sistema: dar de baja al usuario de toda comunicación opcional o comercial y dejarle solo las notificaciones de seguridad críticas, como el cambio de clave.
6. Event: Open / Click (interacción del usuario final)
Eventos opcionales que indican que se descargó la imagen de seguimiento (píxel) o que se hizo clic en un enlace del mensaje, por ejemplo el botón "Confirmar mi cuenta".
Acción en tu sistema: registrar la interacción para medir qué correos se usan. La confirmación de una cuenta debe validarse cuando el usuario abre el enlace en tu propio servidor, no con este evento: algunos filtros de seguridad corporativos abren los enlaces de forma automática.
4. Arquitectura de integración: Cómo procesar Payloads de forma asíncrona sin bloquear tu servidor
Un error habitual al integrar webhooks es procesar toda la lógica de negocio dentro de la misma ruta HTTP que recibe la notificación. Si tu aplicación recibe muchos eventos a la vez (por ejemplo, miles de entregas después de un envío masivo de facturas) e intenta actualizar bases de datos, mandar notificaciones push y generar archivos en esa misma petición, el servidor web se satura y aparecen errores por tiempo de espera (timeouts).
La arquitectura que recomendamos sigue el patrón de desacoplamiento asíncrono con colas de trabajo:
- Proveedor de envío: manda cada evento a tu endpoint por HTTP POST, con el payload en JSON.
- Endpoint de entrada (receptor del webhook): valida la firma HMAC, guarda el paquete y responde
200 OKenseguida. - Cola de mensajes (Redis, RabbitMQ o Amazon SQS): guarda los eventos hasta que se procesen.
- Trabajadores asíncronos (background workers): leen la cola a su ritmo y aplican la lógica de negocio.
- Base de datos principal: recibe la actualización de estado de cada mensaje.
- Recepción rápida y respuesta inmediata
- Tu endpoint HTTP solo debe recibir el payload JSON, validar la firma HMAC y guardar el paquete tal cual en una cola de mensajes (como Redis, RabbitMQ o Amazon SQS). Enseguida debe responderle al proveedor de envío con un
200 OK, en menos de 50 milisegundos. - Procesamiento en segundo plano (workers)
- Procesos independientes (background workers) leen los eventos de la cola a su ritmo, interpretan los estados (
delivered,bounced), actualizan la base de datos principal y avisan a los usuarios sin frenar el servidor web.
5. Seguridad en Webhooks: Validación de firmas criptográficas HMAC para prevenir falsificaciones
Como los endpoints de webhooks son URLs públicas, cualquier persona o bot podría mandarle a tu servidor un HTTP POST falso que simule que un correo rebotó o que un usuario lo marcó como spam, y provocar que se desactiven cuentas de clientes sin motivo.
Para evitarlo, muchos proveedores de envío firman cada evento, por ejemplo con un código de autenticación de mensajes basado en hash (HMAC-SHA256), y agregan en los encabezados HTTP dos datos de seguridad. Los nombres de los encabezados y el método exacto cambian según el proveedor:
- Marca de tiempo de la firma (timestamp)
- La fecha y hora exacta, en formato UNIX, en que se generó la notificación.
- Firma (signature)
- La firma criptográfica que se calcula con el secreto de tu cuenta, la marca de tiempo y el cuerpo del JSON recibido.
La validación en tu backend (por ejemplo, en Node.js con Express y el módulo crypto) sigue tres pasos:
- Rechazar peticiones viejas: si la marca de tiempo tiene más de 5 minutos, responde
400y descarta el evento. Así evitas ataques de repetición (replay attacks). - Calcular la firma esperada: con
crypto.createHmac('sha256', secreto), firma la marca de tiempo junto con el cuerpo de la petición tal como llegó, sin volver a serializar el JSON. - Comparar en tiempo constante: compara la firma recibida con la esperada usando
crypto.timingSafeEqual(después de comprobar que tienen el mismo largo). Si coinciden, el evento pasa al procesador; si no, responde401.
Esta capa asegura que tu backend procese solo eventos auténticos enviados por tu proveedor de envío y descarte cualquier intento de manipulación externa.
6. Diagnóstico y comparativa: Desarrollo ciego sin Webhooks vs. Telemetría transaccional con ROW
| Factor | Desarrollo ciego sin webhooks | Telemetría transaccional con ROW (We Manegit) |
|---|---|---|
| Visibilidad de entrega | Ninguna: el sistema asume que si la API aceptó el pedido, el correo llegó. | Webhooks de entregas, rebotes y quejas conectados con tu sistema. |
| Tratamiento de rebotes | Tarde: la empresa se entera cuando el cliente llama a soporte. | Monitoreo de rebotes, quejas y reputación; si algo cambia, aviso por ticket. |
| Demoras | Imposible de medir: nadie sabe cuánto tarda el correo en llegar. | Monitoreo continuo de entregas, rebotes y demoras. |
| Seguridad del endpoint | Endpoints expuestos a peticiones falsas (spoofing). | Firma de cada evento validada por tu backend antes de procesarlo. |
| Experiencia del usuario | Pantallas que no avisan si el correo del usuario rebotó. | Avisos al usuario cuando su dirección rebota. |
| Responsable | El equipo de sistemas busca a mano en archivos de registro (.log). | Un Relay Owner que configura, integra y vigila que los correos lleguen. |
7. Preguntas frecuentes sobre latencia, idempotencia de eventos e integración API
¿Qué sucede si el servidor web de nuestra empresa se cae o no responde cuando el proveedor intenta enviar un webhook?
Los proveedores de envío suelen contemplar que tu servidor puede estar en mantenimiento o sin conexión por un rato. Si tu endpoint responde con un error (como 500 Internal Server Error o 502 Bad Gateway) o no contesta dentro del tiempo límite, el proveedor vuelve a intentar el envío del evento con pausas cada vez más largas, hasta recibir un 200 OK. La cantidad de reintentos y el plazo máximo cambian según el proveedor: conviene conocerlos y tener una alerta si tu endpoint empieza a fallar.
¿Por qué la idempotencia es obligatoria al procesar webhooks de correo?
Porque un mismo evento puede llegar más de una vez, por ejemplo si tu servidor lo procesó pero la conexión se cortó justo antes de devolverle el 200 OK al proveedor. Si tu backend no es idempotente, puede repetir acciones en tu base de datos (restar dos veces un saldo o enviar dos alertas). Guarda el message_id y el event_id en una tabla de auditoría: si el evento ya se procesó, el sistema ignora el duplicado y responde 200 OK de inmediato.
¿Se pueden enviar metadatos personalizados en el payload del webhook para vincularlos con nuestros usuarios?
Sí, en la mayoría de los proveedores. Al disparar el correo por API o con encabezados SMTP propios, puedes adjuntar pares clave-valor que tu sistema necesite para identificar el contexto (por ejemplo, user_id: "usr_9981", invoice_id: "inv_4421" o environment: "production"). El proveedor devuelve esos mismos datos en el payload de cada evento (delivered, bounced, clicked), y tu backend puede actualizar los registros sin consultas adicionales a la base de datos.
¿Cómo ayuda el servicio ROW de We Manegit a integrar esta telemetría en tu empresa?
Asignamos un Relay Owner que configura y autentica tu dominio de envío, conecta tu sistema con el proveedor de envíos que mejor se ajusta a tu caso y monitorea rebotes, quejas y reputación. En el plan Integración, además, conecta los webhooks de entregas, rebotes y quejas con tu sistema, revisa tu código de envío con tu equipo y deja un monitoreo continuo de entregas, rebotes y demoras. Si algo cambia, te avisa por ticket.
Revisemos qué sabe tu sistema de sus propios correos
Cuéntanos qué correos envía tu plataforma y con qué proveedor. Revisamos tu configuración de envío y qué eventos estás recibiendo, y te respondemos con el próximo paso para que tu equipo sepa si cada correo llegó.
Hablemos