Webhooks transaccionales

Los webhooks permiten que su aplicación reciba notificaciones en tiempo real cuando algo ocurre con un correo electrónico transaccional después de enviarlo. En lugar de consultar la API para comprobar el estado de entrega, Flexmail envía una solicitud HTTP POST a su endpoint en el momento en que se produce un evento.

Esto es especialmente valioso para el correo transaccional: puede tomar medidas inmediatas cuando un restablecimiento de contraseña tiene un rebote, cuando se entrega una confirmación de pedido o cuando un destinatario marca un mensaje como spam.

Eventos de webhook

Flexmail envía una notificación de webhook para cada uno de los siguientes eventos:

  • Enviado: el mensaje fue aceptado y entregado al servidor de correo receptor.
  • Entregado: el servidor de correo receptor confirmó la entrega en el buzón del destinatario.
  • Rebotado: la entrega falló. Los rebotes duros indican un problema permanente (la dirección no existe); los rebotes suaves indican un problema temporal (buzón lleno, servidor no disponible).
  • Abierto: el destinatario abrió el mensaje.
  • Clic: el destinatario hizo clic en un enlace rastreado del mensaje.
  • Queja: el destinatario marcó el mensaje como spam.

Nota

El seguimiento de aperturas y clics requiere que estén habilitados el píxel de seguimiento y el encapsulado de enlaces. Los eventos de entrega dependen de que el servidor de correo receptor confirme la entrega: no todos los servidores lo hacen.

Configurar un endpoint de webhook

Su endpoint de webhook es una URL en su servidor que acepta solicitudes HTTP POST y devuelve una respuesta 200 para confirmar la recepción.

Requisitos para su endpoint

  • Acepta solicitudes HTTP POST.
  • Es accesible públicamente a través de HTTPS.
  • Devuelve un código de estado HTTP 2xx dentro de un tiempo de espera razonable para confirmar la recepción.
  • Procesa el payload de forma asíncrona si su lógica de manejo es lenta: responda inmediatamente y procese en segundo plano para evitar tiempos de espera agotados.

Registrar su endpoint en Flexmail

La configuración del endpoint de webhook se realiza a través de la API. El proceso de registro completo y las opciones disponibles están documentados en la documentación de la API en email-api.flexmail.eu/documentation, en la sección de Webhooks.

Payload del webhook

Cada notificación de webhook es una solicitud HTTP POST con un cuerpo JSON. El payload contiene el tipo de evento, una marca de tiempo, el ID del mensaje y la dirección de correo del destinatario. Dependiendo del evento, se incluyen campos adicionales; por ejemplo, un evento de rebote incluye el tipo de rebote y el motivo, y un evento de clic incluye la URL en la que se hizo clic.

Un payload típico tiene este aspecto:

{ "event": "delivered", "timestamp": "2024-11-15T09:32:00Z", "messageId": "abc123", "recipient": "customer@example.com" }

La especificación completa del payload para cada tipo de evento está en la documentación de la API.

Qué hacer con los eventos de webhook

Rebotes

Cuando reciba un evento de rebote duro, marque esa dirección de correo en su sistema. Deje de enviarle correos e investigue si la dirección se introdujo correctamente. Seguir enviando a direcciones con rebote duro daña su reputación como remitente.

Quejas de spam

Cuando un destinatario marca un correo transaccional como spam, suprima esa dirección de inmediato. Incluso si el correo era genuinamente transaccional (una confirmación de pedido, por ejemplo), el destinatario ha señalado que no desea recibir correos suyos. Seguir enviando es perjudicial para su reputación y puede ser un problema legal.

Confirmaciones de entrega

Para mensajes urgentes como restablecimientos de contraseña o códigos de autenticación en dos pasos, puede usar el evento de entrega para confirmar que el correo llegó a la bandeja de entrada. Si no llega ninguna confirmación de entrega dentro de un plazo razonable, puede mostrar un mensaje en su interfaz de usuario sugiriendo al usuario que revise su carpeta de spam o vuelva a intentarlo.

Consejo

Confirme las solicitudes de webhook de inmediato con una respuesta 200 y luego procese el payload en un trabajo o cola en segundo plano. Si su manejador tarda demasiado en responder, Flexmail puede agotar el tiempo de espera y reintentar la solicitud, lo que puede llevar a un procesamiento duplicado.

Reintentos

Si su endpoint no devuelve una respuesta exitosa, Flexmail reintentará la notificación de webhook. Haga que su manejo de eventos sea idempotente: procesar el mismo evento dos veces debe producir el mismo resultado que procesarlo una sola vez. Use el ID del mensaje y el tipo de evento juntos para deduplicar.

Próximos pasos

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.