Aplica a: EnvíaloSimple Transaccional · Tiempo estimado: lectura
¿Qué vas a lograr?
Configurar webhooks para recibir notificaciones automáticas en tiempo real cuando ocurre un evento en tus envíos transaccionales (entrega, apertura, clic, rebote, etc.).
Crear un webhook
Opción 1
Desde Dominios → Webhooks: seleccioná el dominio y hacé clic en Crear webhook.
Opción 2
Desde Dominios → Listado: hacé clic sobre el dominio o en los tres puntos y seleccioná Gestionar
Hacé clic en Webhooks → Gestionar webhooks
Seleccioná el dominio y hacé clic en Crear webhook.
Configuración
Al crear el webhook, completá los siguientes datos:
- Nombre del webhook
- Dominio sobre el que se informarán los eventos
- URL de destino donde se enviarán las notificaciones (debe incluir http:// o https://)
- Eventos que querés recibir: Correo procesado, Correo entregado, Abierto, Cliqueado, Rebote duro, Rebote blando, Contacto excluido, Queja, Falla de envío
- Método de autenticación:
Basic Auth — agrega usuario y contraseña a los headers de la notificación
Bearer Token — agrega un header Authorization: Bearer {token}. El servidor de destino valida el token
Signing Key — genera un hash a partir del timestamp y un valor aleatorio. El servidor puede validar la autenticidad comparando el hash recibido con el que calcule por su cuenta
Ninguno — sin mecanismo de validación
Funcionamiento
Cuando se produce un evento, se envía una notificación inmediata a la URL configurada mediante una llamada POST con body JSON. Los campos del payload son:
Campo | Descripción |
ts | Fecha del evento (timestamp). |
event | Evento que se produjo. Los eventos posibles son: processed, sent, read, click, rejected_soft, rejected_hard, failed, excluded o complaint. |
mail.id | Id único del email. |
mail.domain | Dominio desde dondé salió el email. |
mail.from | Remitente del email. |
mail.to | Destinatario del email. |
mail.subject | Asunto del email. |
mail.type | Tipo de email: html o text. |
mail.status | Estado actual del envío. |
mail.channel | Canal de envío: smpt (mediante SMTP) o http (mediante API). |
mail.user_variables | Variables de email. Ver sección Uso de variables. |
mail.created_date | Fecha que se empezó a enviar el email (timestamp). |
mail.updated_date | Fecha de última vez que el mail cambió de estado (timestamp). |
signature.token | Valor aleatorio para la autenticación mediante Signature. |
signature.signature | Hash para la autenticación mediante Signature. |
metadata.ip | IP desde donde se realizó la apertura/clic |
metadata.device_class | Dispositivo donde se realizó la apertura/clic |
metadata.ua_class | Tipo de Cliente/Navegador donde se realizó la apertura/clic |
metadata ua_family | Cliente/Navegador donde se realizó la apertura/clic |
metadata.url | Url donde se hizo clic |
Ejemplo:
{
"ts": 1690997197,
"event": "read",
"mail": {
"id": "64ca91a5d85305933c06c02a",
"domain": "dominiopruebas.com",
"from": "\"Empresa S.A.\" <[email protected]>",
"to": "\"Juan Pérez\" <[email protected]>",
"subject": "Prueba Webhooks",
"type": "html",
"status": "processed",
"channel": "http",
"user_variables": {
"variable1": "ejemplo",
"variable2": "123",
"variable3": true
},
"created_date": 1690997157,
"updated_date": 1690997160
},
"metadata": {
"ip": "190.230.245.155",
"device_class": "smartphone",
"ua_class": "mobile_browser",
"ua_family": "Chrome Mobile",
"url": "https://www.google.com"
}
"signature": {
"token": "o7VWpdKtmkNHtMUO4DtYZ12Ub8oDnTGZ",
"signature": "9e51d7b89118014db50e2ad77f4280c40c7368652b4c765a2de158bfc3b99ec7"
}
}Uso de variables
Es posible enviar variables personalizadas con cada correo para que sean incluidas en el body de las notificaciones de webhook.
Desde la API — incluí las variables en el campo user_variables:
json
{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Asunto del correo",
"html": "<html><body>Hola mundo</body></html>",
"user_variables": {
"variable1": "ejemploString",
"variable2": 123456,
"variable3": true
}
}Desde SMTP — agregá el header X-EnvialoSimple-Vars:
X-EnvialoSimple-Vars: {"variable1": "valor1", "variable2": "valor2"}Reglas para el uso de variables:
Máximo 10 variables por email
Los valores deben ser escalares: string, integer, float o boolean
Los nombres de las variables: máximo 64 caracteres
Los valores: máximo 1024 caracteres
El incumplimiento de estas reglas genera un error en la API o deja user_variables en null en SMTP