Emailing
Los webhooks son una potente forma de recibir notificaciones en tiempo real cuando se producen eventos en tus campañas de email. Esta completa guía te enseñará qué son los webhooks, cómo funcionan con los sistemas de correo electrónico y cómo implementar la funcionalidad de webhooks de Mailjet para realizar un seguimiento en tiempo real de eventos de email como aperturas, clics, rebotes y mucho más.
Al final de esta guía sabrás cómo configurar y optimizar los puntos de conexión de los webhooks, gestionar distintos tipos de eventos y aplicar las mejores prácticas para un procesamiento de eventos de email fiable y adaptable.
Un webhook es una forma sencilla de que un sistema notifique a otro que «acaba de ocurrir algo». Es una solicitud HTTP POST enviada a una URL que tú proporcionas (tu «punto de conexión de webhook» ) que contiene una carga útil JSON que describe el evento. A diferencia de las API que sondeas según un calendario, los webhooks se basan en eventos, ya que envían datos solo cuando hay algo nuevo de lo que informar.
Piensa en los webhooks como la versión de internet de una llamada telefónica: en lugar de comprobar repetidamente si ha ocurrido algo, el sistema te llama inmediatamente cuando ocurre.
Los webhooks ofrecen varias ventajas para el email marketing y los flujos de trabajo de emails transaccionales:
Entender la diferencia entre los webhooks y el sondeo tradicional de las API de email ayuda a ilustrar por qué los webhooks son a menudo la mejor opción:
| Sondear con API | Webhooks |
|---|---|
| Extrae datos según un temporizador establecido, aunque no haya cambiado nada | Notificaciones push basadas en eventos |
| Más peticiones y uso de ancho de banda | Menos solicitudes, más eficientes |
| Información estratégica retrasada debido a los intervalos entre sondeos | Actualizaciones instantáneas cuando se producen eventos |
| Programación compleja y gestión de estados | Flujos de trabajo de automatización más sencillos |
Mailjet puede enviar notificaciones webhook para los siguientes eventos de email:
Cada webhook contiene una carga JSON con información específica del evento. Aquí tienes ejemplos de tipos de eventos habituales:
{
"event": "open",
"time": 1433103519,
"MessageID": 19421777396190490,
"email": "api@mailjet.com",
"mj_campaign_id": 7173,
"mj_contact_id": 320,
"customcampaign": "",
"CustomID": "helloworld",
"Payload": "",
"ip": "127.0.0.1",
"geo": "US",
"agent": "Mozilla/5.0 ..."
}
{
"event": "bounce",
"time": 1430812195,
"MessageID": 13792286917004336,
"email": "bounce@mailjet.com",
"blocked": true,
"hard_bounce": true,
"error_related_to": "recipient",
"error": "user unknown"
}
Cada tipo de evento requiere diferentes estrategias de tratamiento:
Seguir estas buenas prácticas garantiza un procesamiento fiable de los webhooks y un rendimiento óptimo:
Mailjet reintenta automáticamente las entregas webhook fallidas durante un máximo de 24 horas si tu punto de conexión no devuelve una respuesta 200 OK. Si persisten los errores repetidos, se puede llegar a suspender la URL del webhook. Puedes configurar una URL alternativa para garantizar la entrega continua de eventos.
Puedes configurar los webhooks de Mailjet utilizando la API o la interfaz web. Aquí tienes ambos enfoques:
Este método ofrece más control y es ideal para implantaciones automatizadas.
Decide qué eventos quieres rastrear: sent (enviado), open (abierto), click (cliqueado), bounce (rebote), blocked (bloqueado), spam (no deseado) o unsub (baja).
Utiliza el recurso eventcallbackurl para configurar tu webhook:
curl -X POST \
https://api.mailjet.com/v3/REST/eventcallbackurl \
-H 'Authorization: Basic <base64_encoded_api_key:secret>' \
-H 'Content-Type: application/json' \
-d '{
"EventType": "open",
"Url": "https://ejemplo.com/webhooks/mailjet/open",
"Version": 2
}'
Notas de configuración:
Envía un email de prueba y realiza la acción rastreada (abrir, hacer clic, etc.) para verificar que recibes eventos webhook.
Para los equipos que prefieren una interfaz visual:
Aquí tienes implementaciones mínimas de receptores webhook en lenguajes de programación populares:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/mailjet/open', (req, res) => {
// 1. Persiste rápidamente los datos del evento
console.log('Received webhook:', req.body);
// TODO: Guardar en la cola o en la base de datos
// await saveToQueue(req.body);
// 2. Acusar recibo inmediatamente
res.status(200).send('ok');
});
app.listen(3000, () => {
console.log('Servidor de webhook en puerto 3000');
});
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/mailjet/open', methods=['POST'])
def handle_open_event():
data = request.get_json()
# Procesa los datos del webhook
print(f"Webhook recibido: {data}")
# TODO: Guardar en cola o base de datos
# save_to_queue(data)
return jsonify({"status": "ok"}), 200
if __name__ == '__main__':
app.run(port=3000)
Aquí tienes algunos consejos que te ayudarán a sacar aún más partido de los webhooks.
Utiliza Version=2 en la configuración de tu webhook para reducir la sobrecarga HTTP al recibir múltiples eventos en peticiones por lotes:
{
"EventType": "open",
"Url": "https://example.com/webhooks/mailjet/batch",
"Version": 2
}
Utiliza los parámetros CustomID y EventPayload en tus llamadas a la API de envíos para que los eventos de webhook sean más fáciles de correlacionar con tus sistemas internos:
{
"Messages": [{
"To": [{"Email": "user@example.com"}],
"Subject": "Welcome!",
"TextPart": "Welcome to our service!",
"CustomID": "user-123-welcome",
"EventPayload": "campaign=onboarding&segment=new_users"
}]
}
Para aplicaciones de gran volumen considera la transmisión de eventos a servicios de cola de terceros:
Mailjet envía eventos de enviado, abierto, cliqueado, rebote, bloqueado, spam y baja. Cada uno contiene el MessageID, identificadores de contacto y de campaña, y detalles específicos del evento (como la URL para los eventos de clic).
Los eventos se envían poco después de producirse, normalmente en cuestión de segundos. Si tu punto final no responde con HTTP 200 OK, Mailjet reintenta la entrega durante un máximo de 24 horas.
Sí. Configura la entrega agrupada estableciendo Version=2 en tu eventcallbackurl para que Mailjet agrupe varios eventos en una solicitud POST.
Utiliza HTTPS, protege el punto de conexión con autenticación básica y restringe el acceso mediante filtrado de IP o pasarelas API. Procesa siempre las cargas útiles en el servidor y nunca expongas los puntos de conexión de los webhooks a las aplicaciones cliente.
Sigue esta lista de comprobación para implementar con éxito los webhooks de Mailjet:
Ahora que conoces los fundamentos y la implementación de los webhooks, considera la posibilidad de explorar estas funciones relacionadas de Mailjet:
Los webhooks proporcionan una forma potente y eficaz de recibir notificaciones en tiempo real sobre eventos de email. Al implementar los webhooks de Mailjet con una gestión de errores adecuada, medidas de seguridad y procesamiento asíncrono, puedes crear flujos de trabajo de email responsive y basados en datos que mejoren la experiencia del cliente y la eficacia operativa.
Recuerda que debes empezar de forma sencilla, supervisar de cerca tu implementación y adaptar tu procesamiento de webhooks a medida que aumente tu volumen de emails. Con la base proporcionada en esta guía, estás preparado para aprovechar todo el poder del seguimiento de eventos de email en tiempo real.
