Tu guía para usar webhooks
Ya sabes que un email no es algo que se envía y de lo que te puedas olvidar. Cuando envías un mensaje, quieres saber cómo hacer un seguimiento y responder a cualquier problema, ¿verdad? Al fin y al cabo, saber cómo están funcionando tus emails te ayuda a mantener tu reputación como remitente y tus tasas de entregabilidad. Al dirigir un webhook a tu CRM preferido, tu equipo puede ver métricas de interacción relevantes de forma rápida y sencilla, y tomar decisiones basadas en información de última hora. Antes de sumergirnos en los casos de uso, deberíamos repasar los conceptos básicos sobre los webhooks.
¿Qué son los webhooks?
En pocas palabras, los webhooks son notificaciones que envían datos de eventos a otra aplicación después de que ocurra el evento. Actúan como una API inversa, donde, en lugar de consultar un punto de conexión de la API repetidamente en busca de actualizaciones, el webhook te envía la actualización mediante una solicitud HTTP. Webhooks son una forma en que las aplicaciones comunican información a través de la automatización y devoluciones de llamada HTTP personalizadas (similares a los mensajes SMS), habitualmente iniciadas por un disparador como la entrega exitosa de un email o una notificación de rebote.
En una arquitectura basada en eventos, esto resulta especialmente potente. Por ejemplo, cuando proporcionas a tu aplicación bancaria tu información de depósito directo y número de teléfono, y te envían un mensaje SMS indicando que acabas de recibir un ingreso, un webhook es lo que hace posible que tu banco envíe ese mensaje de texto con actualizaciones pertinentes.
¿Para qué se utilizan los webhooks?
Los webhooks se utilizan para crear notificaciones en torno a eventos específicos. Como los webhooks se basan en HTTP POST, son fáciles de usar. Además, los scripts de webhook pueden escribirse en casi cualquier lenguaje de programación que prefieras, como curl, Ruby, Python, PHP, Java, C# y Go. Una vez capturados los datos del webhook, pueden almacenarse en una base de datos y utilizarse para evaluar la eficacia de las campañas de email o ampliar los perfiles de los destinatarios. Úsalos en una variedad de flujos de trabajo, desde registrar confirmaciones de pedido de comercio electrónico hasta integrar eventos de pago de Stripe en tiempo real en tu backend.
También puedes obtener datos más detallados de los que proporcionaría un panel de control predeterminado si personalizas las métricas que devuelve el webhook.
¿Cómo funcionan los webhooks?
Entonces, ¿cómo funciona un webhook?
Cuando ocurre el evento, el sitio de origen realiza una solicitud HTTP POST a una URL que el equipo de desarrollo ha configurado para recibir el webhook. El equipo de desarrollo puede configurarlos para que los eventos en un sitio provoquen un comportamiento en otro. A continuación, los datos de ese webhook pueden enviarse a la URL configurada como una carga útil de webhook en formato JSON o XML. Aquí tienes los cuatro pasos que necesitas:
Paso uno: elige los datos deseados
La primera decisión del equipo de desarrollo al diseñar su plan de seguimiento y respuesta de email es saber exactamente qué datos quiere recibir. Si el objetivo es saber cuándo están rebotando los emails enviados, la URL del usuario podría ejecutar un script en los POST entrantes para capturar y guardar la dirección de email devuelta en una base de datos local. Ese mismo script podría ampliarse para capturar el nombre del destinatario, el asunto o cualquier otro parámetro que proporcione el webhook.
Empecemos explorando la solicitud POST del webhook, que puede codificarse como: application/x-www-form-urlencoded para la mayoría de los mensajes, y como multipart/form-data si hay un adjunto incluido en el mensaje. El método de solicitud POST está diseñado para pedir a un servidor web que acepte los datos incluidos en el cuerpo del mensaje de solicitud y los almacene.
Este es un ejemplo de un HTTP POST realizado por Mailgun a un URI en Runescope. Ten en cuenta que el encabezado Content Type se define como application/x-www-form-urlencoded:
ACCEPT: */*
ACCEPT-ENCODING: GZIP
CONNECTION: CLOSE
CONTENT-LENGTH: 1325
CONTENT-TYPE: APPLICATION/X-WWW-FORM-URLENCODED
HOST:
USER-AGENT: MAILGUN/TREQ-0.2.
El cuerpo del mensaje contiene parámetros almacenados como pares clave-valor. (Profundizaremos más en los datos que se publican en la sección de abajo). Dado que los datos están codificados, parecerán texto incomprensible. Así es como se vería habitualmente el cuerpo decodificado:
DOMAIN: BEATNIKZ.NET
EVENT: DELIVERED
MESSAGE-HEADERS: [["RECEIVED", "BY LUNA.MAILGUN.NET WITH HTTP; WED, 07 JAN 2015 00:44:03 +0000"], ["MIME-VERSION", "1.0"], ["CONTENT-TYPE", ["TEXT/PLAIN", {"CHARSET": "ASCII"}]], ["SUBJECT", "HELLO"], ["FROM", "TAG TEST "], ["TO", "MGBOX01@GMAIL.COM"], ["X-MAILGUN-TAG", "WEB APP SEPTEMBER NEWSLETTER"], ["X-MAILGUN-TAG", "NEWSLETTERS"], ["MESSAGE-ID", ""], ["X-MAILGUN-SID", "WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0="], ["DATE", "WED, 07 JAN 2015 00:44:11 +0000"], ["SENDER", "NOLAN=YBEATNIKZ.NET@BEATNIKZ.NET"], ["CONTENT-TRANSFER-ENCODING", ["7BIT", {}]]]
MESSAGE-ID:
RECIPIENT: MGBOX01@GMAIL.COM
SIGNATURE: EB9FE5C673522299A2259052E56487E54F4D2486A0F1582E91D2C17114A6398
TIMESTAMP: 1420591452
TOKEN: E40542A95B5A6989B5E226CC0E9BB2F120478AF8EE594F884C
X-MAILGUN-SID: WYI3NGU3NYISICJTZ2JVEDAXQGDTYWLSLMNVBSISICI0MGRKIL0=
X-MAILGUN-TAG: WEB APP SEPTEMBER NEWSLETTER
X-MAILGUN-TAG: NEWSLETTERS
Paso dos: adjunta datos a los mensajes
Al enviar un email, algunos ESP permiten a los usuarios adjuntar datos a sus mensajes transfiriendo datos personalizados a la API o a los puntos de conexión SMTP. Los datos se representarán como un encabezado dentro del email y normalmente tienen formato JSON. Estos datos personalizados se incluirían entonces en cualquier evento de webhook relacionado con el email que los contiene. Se puede incluir más de un encabezado y sus valores se combinarán.
Ejemplo:
X-MAILGUN-VARIABLES: {"FIRST_NAME": "JOHN", "LAST_NAME": "SMITH"}
X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}
Para añadir este encabezado a un mensaje:
USING API: PASS THE FOLLOWING PARAMETER, "V:MY-CUSTOM-DATA" => "{"MY_MESSAGE_ID": 123}".
USING SMTP: ADD THE FOLLOWING HEADER TO THE EMAIL, "X-MAILGUN-VARIABLES: {"MY_MESSAGE_ID": 123}".
Alternativamente, puedes eliminar fácilmente un webhook existente:
A veces resulta útil categorizar el tráfico de email saliente basándose en algún criterio, como separar los emails de registro de los de recuperación de contraseña o de los comentarios de los usuarios. El ESP puede permitir etiquetar cada mensaje saliente con un valor personalizado. Estos valores se convierten en etiquetas que pueden recuperar o agregar estadísticas de entregabilidad. Para adjuntar una etiqueta a un mensaje de webhook, incluye uno o más O:TAG en él.
Ejemplo de código de etiquetado:
CURL -S --USER 'API:YOUR_API_KEY' \
HTTPS://API.MAILGUN.NET/V3/YOUR_DOMAIN_NAME/MESSAGES \
-F FROM='SENDER BOB ' \
-F TO='ALICE@EXAMPLE.COM' \
-F SUBJECT='HELLO' \
-F TEXT='TESTING SOME MAILGUN AWESOMNESS!' \
-F O:TAG='SEPTEMBER NEWSLETTER' \
-F O:TAG='NEWSLETTERS'
Paso tres: configura la URL
Para recibir los datos de un webhook, los usuarios deben proporcionar a su ESP una URL a la que enviar las solicitudes. Esto significa que también hay que configurar la URL en la aplicación, para que sea accesible desde la web pública y distintas direcciones IP (de ahí la necesidad de contar con medidas de seguridad). Los webhooks del ESP realizarán entonces el POST de los datos en la URL como application/x-www-form-urlencoded o multipart/form-data.
Paso cuatro: crea scripts para capturar los datos
El paso final consiste en añadir scripts a la URL para capturar los datos que proporcionan los webhooks y procesarlos como el equipo de desarrollo considere oportuno. Aquí es donde puedes usar tu creatividad y ser tan minucioso como quieras con los atributos que deseas recopilar. La mejor manera de verlo es con un ejemplo.
Un caso de uso para un webhook podría ser el seguimiento de rebotes de email. Para ello tendrás que capturar un adjunto y guardar el archivo de forma local. Por ejemplo, el siguiente código utiliza una combinación del microframework para Python, Flask y la biblioteca HTTP de Requests. Aquí tienes una aplicación de Flask rápida para capturar un archivo desde un webhook de rebote, mantener el nombre de archivo nativo y guardarlo localmente en tu servidor web.
FROM FLASK IMPORT FLASK
FROM FLASK IMPORT REQUEST
FROM WERKZEUG IMPORT SECURE_FILENAME
APP = FLASK(__NAME__)
@APP.ROUTE('/WEBHOOK', METHODS=['GET', 'POST'])
DEF TRACKING():
#CHECKS IF THE REQUEST IS A POST
IF REQUEST.METHOD == 'POST':
F = REQUEST.FILES['ATTACHMENT-1']
# OBTAINS THE FILESTORAGE INSTANCE FROM REQUEST
FILENAME = SECURE_FILENAME(F.FILENAME)
F.SAVE('/HOME/DIRECTORY/WEBHOOK/'+ FILENAME)
PRINT FILENAME
RETURN "OK"
IF __NAME__ == '__MAIN__':
APP.RUN(HOST='0.0.0.0', PORT=100, DEBUG=TRUE)
Para verlo en acción, ejecuta tu aplicación y pega la URL (por ejemplo: http://yourdomainhere.com:100/webhook) en el webhook de rebote y haz clic en “Test Webhook”. Obtendrás un archivo llamado “message.mime” con:
RECEIVED: BY LUNA.MAILGUN.NET WITH SMTP MGRT 8734663311733; FRI, 03 MAY 2013 18:26:27 +0000
CONTENT-TYPE: MULTIPART/ALTERNATIVE; BOUNDARY="EB663D73AE0A4D6C9153CC0AEC8B7520"
MIME-VERSION: 1.0
SUBJECT: TEST BOUNCES WEBHOOK
FROM: BOB
TO: ALICE
MESSAGE-ID:
LIST-UNSUBSCRIBE:
X-MAILGUN-SID: WYIWNZI5MCISICJHBGLJZUBLEGFTCGXLLMNVBSISICI2IL0=
X-MAILGUN-VARIABLES: {"MY_VAR_1": "MAILGUN VARIABLE #1", "MY-VAR-2": "AWESOME"}
DATE: FRI, 03 MAY 2013 18:26:27 +0000
SENDER: BOB_USER_ID@AWESOME_WORKFLOWS.MAILGUN.ORG
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520
MIME-VERSION: 1.0
CONTENT-TYPE: TEXT/PLAIN; CHARSET="ASCII"
CONTENT-TRANSFER-ENCODING: 7BIT
HI ALICE, DO YOU EXIST ON THIS DOMAIN?
--EB663D73AE0A4D6C9153CC0AEC8B7520--
Estos cuatro pasos te ayudarán a configurar un webhook completo, pero para sacarle provecho, tendrás que activarlo y conocer los parámetros de los eventos.
Eventos y parámetros de los webhooks
Como hemos explicado anteriormente, webhooks se activan mediante eventos específicos. En el ámbito del email, estos eventos incluyen aperturas, clics, solicitudes de baja y otros eventos relacionados con la entrega de emails. Aquí tienes un desglose completo de los eventos de Mailgun que pueden actuar como disparador de un webhook:
- Apertura: este evento ocurre cada vez que un destinatario abre un mensaje. El seguimiento de aperturas se habilita utilizando los parámetros O:TRACKING u O:TRACKING-OPENS al enviar un mensaje.
- Clic: este evento realiza un seguimiento cada vez que un destinatario hace clic en los enlaces de un mensaje de email. Habilita el seguimiento de clics utilizando los parámetros O:TRACKING u O:TRACKING-CLICKS al enviar un mensaje. Igual que con las aperturas, se deben incluir los registros CNAME correspondientes en el DNS del usuario.
- Baja: este evento ocurre cuando un destinatario hace clic en el enlace de “darse de baja” de un mensaje. Tendrás que utilizar el seguimiento de bajas de Mailgun para recibir esta información.
- Queja por spam: no todos los ISP admiten notificaciones de bucle de retroalimentación (“FBL”) en quejas por spam, pero deberías asegurarte de obtener datos de todos los que sí lo hacen.
- Rebote: se dice que un mensaje de email genera un “rebote” si el servidor SMTP del destinatario lo rechaza. Estos se suelen clasificar como rebotes definitivos o temporales de la siguiente manera:
- Fallo permanente (“rebote definitivo”): no se encuentra al destinatario, y el servidor de email del destinatario especifica que dicho destinatario no existe. La aplicación debería dejar de intentar realizar la entrega a los destinatarios no válidos tras un fallo permanente.
- Fallo temporal (“rebote temporal”): el email no se entrega debido a un problema temporal, como una bandeja de entrada llena. Las aplicaciones pueden responder mediante programación a los fallos temporales volviendo a intentarlo un número determinado de veces antes de eliminar la dirección del destinatario de la lista.
- Entregado: una entrega exitosa ocurre cuando el servidor de email del destinatario responde que ha aceptado el mensaje. Dependiendo del evento, los webhooks pueden entregar una gran variedad de parámetros para ayudar a identificar y describir el mensaje en cuestión. A continuación, estos datos se pueden analizar a través de scripts. Algunos de los parámetros más comunes son:
- Evento
- Destinatario
- Dominio de envío
- Encabezados del mensaje
- Detalles de identificación del destinatario: país, región, ciudad, dispositivo, cliente de email y sistema operativo
Dependiendo del ESP, otros parámetros pueden incluir variables personalizadas, etiquetas, nombres de campaña y autenticación o ID de usuario, entre otros. Además, algunos eventos ofrecen más detalles, como una URL en la que se ha hecho clic, el motivo o la descripción de un evento negativo, o códigos especiales que proporcionan detalles específicos sobre el evento.
Protección de los webhooks
Una URL de recepción debe ser pública. Para mantener los contenidos seguros, los webhooks deberían incluir una marca de tiempo de firma y un token para crear un hashmap. Un hashmap es solo una manera de almacenar elementos con identificadores. El hashmap también utiliza una clave de API para verificar que los datos proceden del ESP del equipo de desarrollo. Deberías programar tu aplicación para que compruebe este hashmap y lo compare con el del ESP, permitiendo que se realice el POST solo si coinciden.
Para verificar que el webhook procede de su ESP, debes vincular los valores de marca de tiempo y token, codificar la cadena resultante con el algoritmo HMAC (utilizando la clave de API proporcionada por el ESP como clave y el modo de resumen SHA256) y comparar el hexdigest resultante con la firma. Además, puedes almacenar el valor del token en la caché local y rechazar cualquier otra solicitud que tenga el mismo token. Esto evitará que los hackers utilicen el token para repetir acciones o cambiar su dirección.
El código de estado que devuelvas (por ejemplo, 200 OK) indica al remitente si el webhook se ha procesado con éxito. Monitoriza siempre estas respuestas para garantizar la resiliencia. Otro nivel de seguridad sería comprobar la marca de tiempo para confirmar que el intento de POST se ha realizado dentro de un plazo determinado.
A continuación tienes un ejemplo de código en Python que se utiliza para verificar la firma de un webhook:
import hashlib
import hmac
def verify(api_key, token, timestamp, signature):
message = f"{timestamp}{token}"
expected_signature = hmac.new(
key=api_key.encode(),
msg=message.encode(),
digestmod=hashlib.sha256
).hexdigest()
return signature == expected_signature
Creación de webhooks con Mailgun
Puedes encontrar información completa y código para crear y eliminar distintos tipos de webhooks en nuestra documentación, pero a continuación incluimos algunos ejemplos comunes. ¡Échales un vistazo!
Puedes usar nuestra API para crear un nuevo webhook:
POST /domains//webhooks
O actualizar uno:
PUT /domains//webhooks/
Alternativamente, puedes eliminar fácilmente un webhook existente:
DELETE /domains//webhooks/
Además, para obtener información sobre tus webhooks, puedes consultar los detalles sobre cualquier URL de webhook:
GET /domains//webhooks/
Por supuesto, si pusiéramos ejemplos de todas las formas en las que puedes usar nuestra API para crear y optimizar tus webhooks, podríamos estar aquí todo el día. La cuestión es que puedes hacer prácticamente lo que quieras (prometemos no decírselo a tu madre).
Mailgun te lo pone fácil
Aunque existen varios métodos para acceder a los datos generados por la entrega de emails, como los paneles de control de ESP y las llamadas a la API, date un respiro y añade algunos webhooks para facilitar las cosas: son la forma más flexible y eficiente de recopilar datos detallados de los mensajes de email.
En lugar de extraer datos de tu ESP, opta por recibir datos push continuos relacionados con el email en tiempo real. Mailgun facilita el uso de los webhooks, lo que simplifica el trabajo de los equipos que utilizan esta información en tiempo real para tomar decisiones en campañas de email actuales y futuras en distintas aplicaciones y servicios web. Genial, ¿verdad?
¿Sabes qué más es genial? Más información sobre los webhooks. Para obtener información sencilla y paso a paso sobre cómo usar webhooks con Mailgun, consulta nuestra documentación en webhooks. Para profundizar en más temas como este, suscríbete a nuestra newsletter, ya que los webhooks no son lo único que puede proporcionarte datos detallados.
