Usar los webhooks

Los webhooks son un mecansimos para permitir que Acumbamail se comunique con una plataforma online de tu propiedad. Básicamente lo que tienes que hacer es proporcionar una URL que sea capaz de leer los datos que Acumbamail le va a enviar cuando se produzcan determinados eventos. Puedes elegir qué eventos quieres recibir para así provocar menos carga a tu servidor. 

Para qué sirven los webhooks

Los webhooks tienen muchas utilidades, la principal es mantener la sincronización entre tu base de datos y Acumbamail. También se pueden utilizar para tener más información sobre el engagement de tus emails en tu CRM, guardando información de qué clientes abren tus emails. Básicamente son lo contrario a una API, en una API puedes realizar llamadas para hacer que se produzcan determinadas acciones. En un webhook recibirás llamadas cuando se produzcan determinadas acciones. Únicamente tienes que crear una URL en tu sistema web que te permita recibir los eventos que Acumbamail va a enviar. 

Hay dos tipos de webhooks, los que sirven para email transaccional y los que se utilizan para el envío de campañas. En el caso de las campañas, el webhook se configurará para cada una de las listas, ya que pueden proceder de distintas bases de datos, permitiendo así configurar varios webhooks para una campaña, uno para cada una de las listas a las que se envíe dicha campaña. Los webhook que se disparan en el caso del email transaccional se configurarán para toda la cuenta completa. A continuación tienes un listado de los eventos que podrás recibir en tus webhooks, no es obligatorio que elijas todos, podrás recibir únicamente los que te resulten de interés. También se indica en la tabla qué webhooks funcionan únicamente en el servicio de campañas y cuáles en el de email transaccional. 

Evento Se dispara cuando Campañas Email transaccional
Alta Un suscriptor se da de alta en una lista. No
Baja Un suscriptor se da de baja en una lista No
Hard bounce Se envía un email a una dirección que no existe
Queja Un receptor marca un email como correo no deseado
Apertura Un receptor abre un email
Click Un receptor hace click en un email

Configurar webhooks para listas

Para configurar un webhook en una lista debes ir al menú de listas y elegir una de tus listas. Una vez dentro de la propia lista, debes elegir la opción Webhook en la página de la lista:

opción webhook

Una vez hecho esto, aparecerá ante ti la página que te permitirá configurar los eventos que se enviarán a tu url de procesamiento de webhooks. La página es esta:

configurar webhook

En ella debes introducir la URL de tu sistema que procesará los webhooks, será la misma para todos los eventos y tendrás que seleccionar los eventos que quieres recibir. Una vez hecho esto puedes activar o desactivar el webhook cuando lo desees utilizando el botón inferior. Ten en cuenta que este webhook solamente funcionará para los suscriptores que pertenezcan a la lista, por lo que debes configurarlo en cada una de las listas que quieras sincronizar.

Configurar webhooks para email transaccional

Para configurar los webhooks para el email transaccional, debes pulsar el botón SMTP del menú de la parte izquierda y, una vez desplegado SMTP, debes seleccionar la opción Webhook:

seleccionar webhook SMTP

Una vez hecho esto verás una página muy similar a la de listas, que te permitirá introducir la URL de tu sistema que procesará el webhook y, a continuación, seleccionar los eventos que se enviarán a dicha URL y activar el webhook:

configurar webhook smtp

Ten en cuenta que en el servicio de email transaccional los eventos que recibirán son menos, ya que el evento de Alta y Baja de suscriptor no tiene sentido en este servicio, al no haber suscriptores.

Cómo procesar un webhook

Los webhooks realizarán una llamada a la URL que hayas configurado. Esta URL debe estar preparada para recibir los eventos. Se enviarán en formato JSON que vendrá incluido en el body de la petición que realizaremos. Tienes que tener en cuenta que, si tu volumen de envíos es elevado, recibirás un gran número de peticiones en esa URL, por lo que debe estar preparada para recibir los eventos correctamente.  

Las peticiones serán un objeto de JSON, que tendrán la siguiente forma:

El objeto incluirá una serie de eventos, que serán los que se han producido desde que se lanzó la anterior petición. El campo event es el que define el tipo de acción que se está llevando a cabo. Cada acción puede tener campos extra. A continuación, incluimos los campos extra con los parámetros para cada evento:

Entregado:

Parámetro
event El tipo de evento que se va a realizar. En este caso, delivered.
email El email del suscriptor
timestamp Fecha en formato UNIX timestamp

Hard bounces
:
Parámetro
event El tipo de evento que se va a realizar. En este caso: hard_bounces
email el email del suscriptor
timestamp Fecha en formato UNIX timestamp
bounce_reason Nos proporcina el error que ha dado el email

Queja:

Parámetro
event El tipo de evento que se va a realizar. En este caso: complaints
email El email del suscriptor
timestamp Fecha en formato UNIX timestamp

Apertura:

Parámetro
event El tipo de evento que se va a realizar. En este caso: opens
email El email del suscriptor
timestamp Fecha en formato UNIX timestamp

Clic:

Parámetro

event El tipo de evento que se va a realizar. En este caso: clicks
email El email del suscriptor
timestamp Fecha en formato UNIX timestamp