EnvíaloSimple Transaccional: Webhooks

Un webhook es una herramienta que permite a un sistema o aplicación enviar notificaciones sobre un evento específico a otro sistema o aplicación en tiempo real.

De esta manera, al configurar los webhooks de EnvíaloSimple Transaccionales podrás conectarlos a una URL pública (perteneciente al sistema o aplicación de destino) a la cuál se enviarán notificaciones cuando se produzca un evento específico en el envío.

Por ejemplo: entrega, apertura, clics, entre otros. Para comenzar a utilizarlos deberás realizar unas sencillas configuraciones dentro de la herramienta. A continuación te mostramos cómo hacerlo:

Configuración

Dirígete a la sección Mis Dominios ubicada en el menú lateral.
Una vez allí, verás el listado de los dominios que tienes activos. Haz clic en el nombre del dominio al que deseas agregar el Webhook para ingresar al detalle.
En esa página, dirígete al apartado de Webhooks y haz clic en el botón CREAR WEBHOOK.
Este botón te llevará a un apartado donde puedes crear los webhooks y modificarlos una vez que los hayas creado. Ahora haz clic en el botón CREAR WEBHOOK.
En este punto, se abrirá una ventana en la que deberás configurar los siguientes datos:
- Nombre que deseas darle al Webhook
- URL a la cual se enviarán las notificaciones. Recuerda agregar al inicio de tu dirección el formato http(s).
- Eventos de los cuales deseas recibir notificaciones. Las posibles opciones son: Procesado, Entregado, Abierto, Cliqueado, Rebote duro, Rebote blando, Excluido, Queja y Falla de envío
- Método de autenticación: Acá deberás elegir uno de los tres mecanismos de seguridad que ofrecemos para validar de la autenticidad de la llamada recibida o bien no utilizar ninguno.
  
  1) Basic Auth: Este método agrega un nombre de usuario y contraseña a las cabeceras de la notificación realizada. El servidor de destino deberá autenticar estos datos, y responder de forma acorde.
  
  2) Bearer Token: Este método agrega una cabecera Authorization con valor Bearer: {token}, donde {token} será el valor proporcionado por el usuario. Este token es generalmente una API Key o JWT. El servidor de destino deberá comprobar la validez del token recibido y responder de forma acorde.
  
  3) Signing Key: Este método es diferente a los dos anteriores ya que no se presentarán credenciales al servidor remoto. Se le solicita al usuario una key, la cual se utiliza para generar un hash a partir de la concatenación del timestamp (ts) y de un valor aleatorio (token). El timestamp (ts), el valor aleatorio (token) y el hash (signature) son enviados en la notificación. El usuario puede entonces validar la autenticidad de la llamada realizando la misma operación. Si el hash obtenido es idéntico al que se le envió, entonces puede contar con que la llamada es auténtica.
  
  4) Ninguno: No se utilizará ningún mecanismo de validación.

Ten en cuenta que la cantidad de Webhooks que puedes crear depende del plan que hayas contratado.

Funcionamiento

Al producirse el evento se enviará una notificación a la URL del Webhook asociado de forma inmediata, utilizando el método de seguridad seleccionado. La llamada (notificación) siempre será de tipo POST con un body JSON.

Tendrá los siguientes datos:

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.

Ejemplo:

{
"ts": 1690997197,
"event": "read",
"mail": {
"id": "64ca91a5d85305933c06c02a",
"domain": "dominiopruebas.com",
"from": "\"Empresa S.A.\" <empresa@dominiopruebas.com>",
"to": "\"Juan Pérez\" <juan.perez@ejemplo.com>",
"subject": "Prueba Webhooks",
"type": "html",
"status": "processed",
"channel": "http",
"user_variables": {
"variable1": "ejemplo",
"variable2": "123",
"variable3": true
},
"created_date": 1690997157,
"updated_date": 1690997160
},
"signature": {
"token": "o7VWpdKtmkNHtMUO4DtYZ12Ub8oDnTGZ",
"signature": "9e51d7b89118014db50e2ad77f4280c40c7368652b4c765a2de158bfc3b99ec7"
}
}

Uso de variables

Muchas veces los sistemas asignan identificadores internos a los correos que envían. A partir de ahora, es posible pasar variables arbitrarias con cada Email enviado.

Estas variables serán enviadas en el body de las notificaciones enviadas por los Webhooks.

Enviar variables desde API

Se deberá agregar las variables dentro de una key user_variables.

Por ejemplo:

{

"from": "notificaciones@empresa.com",
"to": "cliente@prueba.com",
"subject": "Prueba API con variables",
"html": "<html><body>Hola mundo</body></html>",
"user_variables": {
"variable1": "ejemploString",
"variable2": 123456,
"variable3": true
}

Enviar variables desde SMTP

Para asignar variables a través de SMTP, deben agregarse cabeceras X-EnvialoSimple-Vars al Email:

X-EnvialoSimple-Vars: {"variable1": "valor1", "variable2: , "valor2"}

Al utilizar variables deben tenerse en cuenta las siguientes reglas:

- Sólo se admiten hasta 10 variables por E-Mail.
- Los valores de las variables deben ser valores escalares (string, integer, float o boolean)
- Los nombres de las variables deben ser menores o iguales a 64 caracteres.
- Los valores de las variables deben ser menores o iguales a 1024 caracteres.
- El no cumplimentar con alguna de estas reglas: Producirá un error si se está usando la API o dejará en null el campo user_variables si se está usando SMTP.

Búsqueda