Product
Misma API, nuevos trucos: recibe notificaciones de eventos al momento con los webhooks
Al trabajar en esta actualización de la API, se nos ocurrieron algunas cosas que tal vez tú también hayas pensado:
- ¡Los webhooks son geniales! Todo el mundo debería usarlos.
- Extraer los datos de envío directamente de mis mensajes ahorra tiempo.
Sinceramente, la API de webhooks de Mailgun lleva ya mucho tiempo entre nosotros. Pero con esta actualización, tienes más opciones para comunicarte con nosotros y ver en detalle qué ocurre con tus mensajes.
Veamos los detalles.
Novedades
Entonces, ¿en qué consiste esta actualización?
Mailgun puede ayudarte a recibir notificaciones al momento para que sepas cuándo ha ocurrido algo con tu mensaje. Tienes la opción de usar el sondeo de eventos a través de la Events API, o dejar que nosotros te enviemos los eventos a través de la API de webhooks. Estas alertas tienen los mismos datos que la Events API y se envían a tus URL mediante HTTP POST.
Ahora, obtienes
- Una carga útil de “Application/JSON”
- Hasta 3 URL por evento
- Datos sobre el siguiente tipo de eventos:
- opened – cada vez que un usuario abre uno de tus mensajes
- clicked – cada vez que un usuario hace clic en un enlace de tus mensajes
- unsubscribed – cuando un usuario se da de baja, ya sea de todos los mensajes, de una etiqueta específica o de una lista de correo
- complained – cuando un usuario marca uno de tus emails como spam. Ten en cuenta que no todos los ESP proporcionan esta información.
- delivered – cuando el servidor de email del destinatario responde que ha aceptado el mensaje.
- permanent_fail – hay varias razones por las que Mailgun deja de intentar entregar mensajes y los descarta, lo que incluye rebotes definitivos, mensajes que han alcanzado su límite de reintentos, direcciones que previamente se han dado de baja, rebotado o marcado como spam, o direcciones rechazadas por un ESP.
- temporary_fail – cuando un ESP rechaza un mensaje temporalmente
Lo bueno de esto es que tu código de lógica de negocio se puede utilizar para cualquiera de las dos opciones. La diferencia radica en cómo te conectas a Mailgun. Y dado que cada evento tiene su propio ID único, si resulta que tu punto de conexión http ha fallado por alguna razón, puedes extraer los eventos fácilmente y ordenarlos usando este ID único. Por supuesto, siempre recomendamos gestionar los webhooks de forma asíncrona para que los picos de eventos no supongan un problema.
¿Cómo puedo usar la API?
Ahora veamos cómo configurar un dominio con el webhook “clicked”. En realidad, es un proceso de un solo paso que puedes completar configurando tus URL con curl o tu lenguaje de programación preferido a través de nuestra API HTTP.
Por ejemplo, utilizando el comando curl:
curl -s --user ‘api:YOUR_API_KEY’
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks
-X POST
-F id=clicked
-F url="https://api.your.domain.com/v1/mg/clicked"
-F url="https://api.your.domain.com/v2/mg/clicked"
-F url="https://api.partner.com/v1/you/clicked"
Aquí, “id” debe ser el nombre del webhook (solo un webhook por petición) y “url” debe indicar tu URL (hasta 3 URL por petición).
Y el mensaje de respuesta:
{
"message": "Webhook has been created",
"webhook": {
"urls": [
"https://api.your.domain.com/v1/mg/clicked",
"https://api.your.domain.com/v2/mg/clicked",
"https://api.partner.com/v1/you/clicked"
]
}
}
Los datos recibidos en tus URL deberían ser:
{
“signature”:
{
"timestamp": "1529006854",
"token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",
"signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"
}
“event-data”:
{
"timestamp": 1529006854.329574,
"id": "DACSsAdVSeGpLid7TN03WA",
"event": "delivered",
"tags": [...],
"user-variables": {...},
"message": {
"headers": {
"message-id": "20180618211821.example.org"
}
},
…
}
}
La parte de “event-data” es la misma que devuelve la Events API y contiene: la marca de tiempo del evento, el id único del evento, el nombre del evento, el message-id, tus etiquetas y variables, etc. Como mejor práctica, no olvides verificar la parte de la “signature” (consulta aquí cómo se hace).
Y eso es todo. Fácil, ¿verdad?
¿Puedo enviar eventos a múltiples puntos de conexión?
Sí que puedes. Si necesitas migrar tu aplicación a una nueva versión o enviar eventos al sitio de tu socio, se puede hacer para un máximo de 3 puntos de conexión.
Si quieres ver qué aspecto tiene tu evento o si tienes alguna pregunta para nuestro equipo de asistencia, es fácil configurar un webhook con una URL temporal a nuestro contenedor de peticiones (request bin) en http://bin.mailgun.net y consumir eventos al mismo tiempo.
Aquí tienes un ejemplo de lo que ocurre al usar una API de prueba también, utilizando el siguiente comando curl:
curl -s --user ‘api:YOUR_API_KEY’ \
https://api.mailgun.net/v3/domains/YOUR_DOMAIN_NAME/webhooks/HOOK_NAME/test \
-X PUT \
-F url=YOUR_URL
Aquí, “url” es tu URL (una por petición) y “HOOK_NAME” es un nombre de webhook (consulta la lista anterior; también uno por petición).
Y el mensaje de respuesta:
{
"code" : null,
"message": "{\"message\":\"Post received. Thanks!\"
}
Aquí, “code” indica el código HTTP recibido por tu parte (null significa 200 OK) y “message” muestra el cuerpo HTTP recibido por tu parte o el mensaje de error
Soy usuario de Mailgun, ¿puedo migrar fácilmente a la nueva API?
Sí. Y todos los webhooks antiguos tendrán que migrarse a esta nueva versión. El punto de conexión de la API de webhooks antigua pasó a ser de solo lectura a partir del 15 de abril de 2023, lo que concluye un proceso de obsolescencia que comenzó en marzo de 2022.
Las actualizaciones de productos son importantes y, como somos una empresa de email, se nos da bastante bien enviar actualizaciones para mantenerte al día. ¿Quieres explorar el porqué y el cómo detrás de nuestras decisiones? Suscríbete a nuestra newsletter para obtener más contenido como este.
