Webhooks de entrada

Desde el apartado Desarrolladores (solo visible para cuentas de pago), podrás configurar una serie de webhooks de entrada. Estos constituyen un vía adicional para poder integrar sistemas externos con Acumbamail de una manera rápida y sencilla. A continuación se detalla toda la información sobre cómo configurar y hacer uso de este tipo de webhooks.

En este artículo:

¿Qué es un webhook de entrada?

Un webhook de entrada es un tipo de integración que permite llamar a Acumbamail desde cualquier otro sistema externo para ejecutar una operación.

Dado un conjunto determinado de operaciones, podrás elegir una de ellas y ejecutarla de una forma tan sencilla como realizar una petición HTTP de tipo POST a una URL dedicada generada por cliente y por operación. Esta petición deberá incluir los datos necesarios para poder ejecutar la operación en el cuerpo, en formato JSON.

Webhook de entrada vs. API

Si una operación está disponible por API y a través de un webhook entrante, solo necesitarás configurar la integración por una de las dos vías, ya que el efecto será idéntico. Ambas te permitirán lo mismo, llamar a Acumbamail para que se ejecute una operación determinada. Sin embargo, la diferencia radica en la forma en que se realiza la integración, lo que se resume en la siguiente tabla:

Característica Webhook de entrada API
Autenticación Es transparente. No hay que añadir nada a la petición, ya que la propia url a la que hay que llamar se genera de forma exclusiva por cliente y operación. Hay que añadir manualmente el auth_token de la cuenta en cada petición para poder efectuar la autenticación.
Llamada Se genera una url diferente por cliente y operación. Es necesario realizar una petición HTTP POST a esa url. Cada operación tiene una url fija y común para todos los clientes. A esta se pueden realizar peticiones HTTP POST o GET.
Payload Puedes enviar directamente un JSON generado por el sistema externo, ya que al configurar el webhook podrás mapear los campos que se encontrarán en el JSON recibido y los campos requeridos por la operación. El sistema que hace la llamada debe preparar un payload con un formato específico requerido por la operación.
Facilidad de integración No requiere habilidades de programación. Muchos sistemas permiten configurar automatizaciones donde el usuario solo debe introducir una URL, y el sistema se encarga de realizar la llamada pasando un JSON con información específica. Es más complejo y puede requerir habilidades de programación, ya que es necesario adaptar la información que se envía junto con la petición a un formato específico.

Crear un nuevo webhook de entrada

Una vez se ha accedido a la vista principal de Webhooks de entrada, hay que hacer clic en el botón Nuevo webhook. Esto abrirá un popup donde podrás configurar los detalles de tu webhook:

Cómo acceder a webhooks de entrada

Cómo acceder a webhooks de entrada

  • Nombre: Un nombre para identificar el webhook.
  • Endpoint: Aquí encontrarás la lista de operaciones disponibles, de entre las que deberás elegir una.
  • Payload de entrada: Deberás copiar un JSON de ejemplo generado por el sistema externo que vaya a realizar la llamada, ya que servirá de referencia para poder configurar el mapeo de campos.
  • Activado/Desactivado: Dado un webhook de entrada, para que Acumbamail acepte la llamada asociada a ese webhook, este deberá estar activo. Si por alguna razón no quieres eliminar el webhook pero quieres inhabilitarlo temporalmente, puedes optar por marcarlo como no activo (útil por ejemplo si crees que la URL se puede haber visto comprometida).
  • Mapeo de campos: Se listarán todos los parámetros de entrada necesarios para poder ejecutar la operación. Dado previamente un payload de ejemplo (que será el JSON que genera el sistema externo), dispondrás de un selector donde se incluyen todos los nodos presentes en el JSON, de forma que puedas elegir qué nodo contiene la información asociada a cada parámetro.

Formulario para crear webhook de entrada

Cuando hayas introducido toda la información, puedes hacer clic en el botón de Crear para que se guarde el nuevo webhook de entrada.

Nuevo webhook creado

Nuevo webhook creado

Una vez creado el webhook, debes seguir unos sencillos pasos para que tu integración esté lista y operativa.

¿Qué es el payload de entrada?

El payload de entrada son los parámetros o datos que enviará el sistema externo a Acumbamail cuando llame a la URL de integración. Estos parámetros contendrán la información de interés dependiendo del tipo de endpoint u operación seleccionada.

¿Cómo averiguo el payload de entrada?

Esto depende del sistema externo que quieras integrar con Acumbamail. Algunos permiten visualizar un ejemplo de la información que se va a enviar o incluso configurar distintas opciones para formatear los datos que se van a enviar en la petición. Sin embargo, otros no proporcionan directamente esta información.

En caso de que te resulte difícil obtener un ejemplo de los parámetros de entrada que va a enviar el sistema desde el que se va a hacer la llamada a Acumbamail, puedes hacer uso de un servicio como WebhookSite. Este genera una URL de pruebas a la que podrás llamar desde tu sistema externo y te permitirá visualizar los parámetros recibidos en la llamada de prueba. Una vez visualices los parámetros, podrás copiarlos y pegarlos en el campo "payload de entrada" en Acumbamail.

Finalmente con el webhook de entrada ya creado en Acumbamail, solo tendrás que cambiar la integración que has configurado previamente en el sistema externo, para que en lugar de llamar a la URL de pruebas, llame a la URL real que te proporciona Acumbamail.

¿Qué formato debe tener el payload de entrada?

Actualmente Acumbamail soporta estos dos formatos: JSON y x-www-form-urlencoded. No obstante, te resultará más sencillo configurar el mapeo si los datos se envían en JSON, por lo que si durante la configuración de la integración puedes escoger entre varios formatos, te recomendamos escoger el JSON.

Formato JSON

Si los datos se envían en formato JSON, solo tendrás que copiar un ejemplo de los parámetros que se envían con la llamada en el campo "payload de entrada" y una vez copiado, seleccionar en el apartado de "mapeo de campos" qué nodos del JSON son los que se corresponden con los parámetros de entrada esperados, dependiendo de la operación elegida.

Formato x-www-form-urlencoded

En cambio, si los datos se envían en formato  x-www-form-urlencoded, deberás transformar esta información a formato JSON antes de copiarla en el campo "payload de entrada". Se incluye a continuación un ejemplo de cómo transformar los datos enviados como x-www-form-urlencoded:


 x-www-form-urlencoded JSON
fields%5Bname%5D%5Btype%5D=text&fields%5Bname%5D%5Bvalue%5D=Test&
fields%5Bname%5D%5Brequired%5D=1&fields%5Bemail%5D%5Btype%5D=email&
fields%5Bemail%5D%5Bvalue%5D=test@test.com&fields%5Bemail%5D%5Brequired%5D=1
{
    "fields[name][value]": "Test",
    "fields[name][required]": "1", 
    "fields[name][type]": "text",
    "fields[email][required]": "1", 
    "fields[email][type]": "email",  
    "fields[email][value]": "test@test.com"
}

Operaciones disponibles

En este apartado se describen las operaciones accesibles a través de webhooks de entrada.

Si necesitas una operación adicional que esté presente en la API y no como webhook de entrada, puedes ponerte en contacto con el equipo de soporte y solicitar su inclusión. Tu petición será evaluada y puede que la nueva operación sea añadida.

Añadir suscriptor a una lista

Esta operación permite, dada una lista específica, añadir un suscritor a la misma.

Campos requeridos

Estos son los campos asociados a la operación:

Nombre Obligatorio Tipo esperado Descripción
email Texto La dirección de correo del suscriptor.
double_optin No Booleano (0,1) Por defecto 0 Indica si enviar o no email de confirmación de suscripción a la lista.
welcome_email No Booleano (0,1) Por defecto 0 Indica si enviar o no email de bienvenida al suscriptor.
update_subscriber No Booleano (0,1) Por defecto 0 Indica si actualizar o no la información del suscriptor si este ya existe en la lista.

Hay que tener en cuenta que esta operación requiere un paso adicional, por el cual se asocia el webhook a una lista específica. Aparecerá un selector adicional donde podrás elegir una de entre todas tus listas.

Selector de lista en la que suscribir al suscriptor

Selector de lista en la que suscribir al suscriptor

Esto es necesario porque cada lista tiene diferentes campos que definen a sus suscriptores. Estos campos (a parte de los propios de la operación) también tienen que ser mapeados durante la configuración del webhook de entrada, para saber en qué nodo específico del JSON recibido se puede localizar la información de cada campo. Así, podrás observar que cuando eliges una lista diferente, se actualizan los campos disponibles en el apartado de  Mapeo de campos, añadiéndose los campos propios de la lista.

Ejemplo campos a mapear de una lista concreta

Ejemplo campos a mapear de una lista concreta

Eliminar suscriptor de una lista

Esta operación permite eliminar a un suscriptor de una lista.

Campos requeridos

Estos son los campos asociados a la operación:

Nombre Obligatorio Tipo esperado Descripción
email Texto La dirección de correo del suscriptor.
list_id Número entero El identificador de la lista a la que pertenece el suscriptor.

Desuscribir suscriptor de una lista

Esta operación permite marcar como baja (desuscrito) a un suscriptor de una lista.

Campos requeridos

Estos son los campos asociados a la operación:

Nombre Obligatorio Tipo esperado Descripción
email Texto La dirección de correo del suscriptor.
list_id Número entero El identificador de la lista a la que pertenece el suscriptor.

Enviar un SMS

Esta operación permite eliminar a un único SMS a un receptor dado.

Campos requeridos

Estos son los campos asociados a la operación:

Nombre Obligatorio Tipo esperado Descripción
body Texto El contenido del mensaje.
recipient Número de teléfono El número de teléfono del receptor (debe incluir prefijo).
sender Texto El nombre del emisor.

Enviar un email transaccional

Esta operación permite enviar un email a un suscriptor específico.

Campos requeridos

Estos son los campos asociados a la operación:

Nombre Obligatorio Tipo esperado Descripción
body Texto El contenido del email.
category No Número entero La categoría del envío.
to_email Texto La dirección de correo del receptor.
from_email Texto La dirección de correo del emisor.
bcc_email No Texto La dirección de correo en copia oculta.
subject Texto El asunto del email.

Enviar una campaña con plantilla

Esta operación permite crear y enviar una campaña a una o más listas, eligiendo una de tus plantillas personalizadas como contenido.

Campos requeridos

Estos son los campos asociados a la operación:

Nombre Obligatorio Tipo esperado Descripción
name Texto El nombre interno de la campaña.
from_name Texto El nombre del emisor.
from_email Texto La dirección de correo del emisor.
subject Texto El asunto del email.
lists Una lista de número enteros La lista de identificadores de las listas receptoras.
template_id Número entero El identificador de la plantilla que se usará como contenido del email.
Mapeo del campo lists

Se destaca aquí el caso especial del campo "lists". En este campo hay que pasar el identificador de la lista o listas receptoras de la campaña. En caso de que sea más de una lista, el JSON recibido deberá contener una clave con una serie de identificadores en formato lista.

No obstante, al crear el webhook de entrada, en el campo Payload de entrada, tendrás que copiar tu JSON añadiendo comillas al listado. De esta manera el nodo que contiene las listas se interpretará como un nodo final que contiene un valor y no uno intermedio. A continuación se presenta un JSON de ejemplo (podría tener cualquier otro formato) para ilustrarlo:

JSON recibido en la petición al invocar la URL Payload de entrada (copiar con comillas)
{
    "data": {
        "name": "My campaign",
        "from": "Me",
        "email": "my.email@company.com",
        "subject": "My subject",
        "template": 1111,
        "lists": [2222, 2223]
    }
}
{
    "data": {
        "name": "My campaign",
        "from": "Me",
        "email": "my.email@company.com",
        "subject": "My subject",
        "template": 1111,
        "lists":  "[2222, 2223]"
    }
}

Valores de retorno

En respuesta a una petición recibida, siempre se devolverá un JSON cuyo contenido dependerá:

  • De la operación solicitada.
  • De si se ha podido ejecutar satisfactoriamente o se ha producido algún error.

Respuesta ante éxito

La siguiente tabla recoge el estado y el contenido en formato JSON de la respuesta devuelva para cada operación cuando esta se ha podido ejecutar satisfactoriamente.

Operación Estado JSON
Añadir suscriptor 201
  • id: Es el identificador único del suscriptor.
  • email: La dirección de correo del suscriptor.
Borrar suscriptor 201
  • email: La dirección de correo del suscriptor
Desuscribir suscriptor 201
  • JSON vacío
Enviar SMS 201
  • id: Es el identificador único del SMS enviado
Enviar email transaccional 200
  • key: Es un identificador único del email enviado
Enviar campaña con plantilla 200
  • id: Es el identificador único de la campaña

Respuesta ante error

Para cualquier operación, en caso de no poder ser ejecutada, se devolverá un JSON que incluirá un mensaje descriptivo del error bajo la clave "error". En la siguiente tabla se incluyen los posibles códigos de error que puede devolver una llamada:

Estado Posible motivo
400
  • Alguno de los parámetros recibidos no contiene un valor válido, o
  • Se ha configurado mal el mapeo y no se ha podido localizar alguno de los parámetros en el JSON recibido.
403
  • Acceso denegado porque el usuario ha pasado de plan de pago a gratuito, o
  • Acceso denegado porque el webhook de entrada solicitado está desactivado.
404
  • Alguno de los parámetros recibidos alude a un elemento que no existe (suscriptor, lista, etc.), o
  • La URL no se puede asociar a ningún webhook de entrada.

Actualizar y borrar un webhook de entrada

Dada la lista de webhooks de entrada que has creado, en el menú de acciones puedes tanto actualizar la configuración de un webhook como eliminarlo.

Para actualizar la configuración de un webhook, solo tienes que hacer clic en el botón de Acciones y ahí seleccionar la opción de Editar. Esto abrirá el popup con toda la información asociada al webhook. Aquí podrás realizar los cambios que necesites, antes de hacer clic en el botón Actualizar para que se guarden los cambios.

Editar un webhook existente

Editar un webhook existente

Para eliminar un webhook, solo tienes que hacer clic en el botón de  Acciones y ahí seleccionar la opción de Borrar. Recuerda que, en lugar de borrarlo, también puedes desactivar un webhook si temporalmente no lo necesitas.

Eliminar un webhook

Eliminar un webhook

Cómo realizar la integración

Una vez creado un webhook de entrada y estando este activo, es momento de probar la integración.

Dada la lista de webhook creados, haz clic en el botón de  Acciones y ahí selecciona la opción de Copiar URL. Esto colocará en el portapapeles la URL específica creada para este webhook.

Cómo copiar la url de integración

Cómo copiar la url de integración

Ahora solo falta realizar la configuración en el sistema externo que vaya a realizar la llamada. Dado el evento que tiene que disparar la operación en Acumbamail, debes configurarlo de la siguiente manera:

  • Debe realizar una petición HTTP de tipo POST a la URL que acabas de copiar. La URL solo responderá a peticiones de tipo POST y HEAD.
  • En el cuerpo de la petición debe enviar la información generada, preferentemente como un raw JSON, cuyo content type sería "application/json; charset=utf-8". También está soportado el content type "application/x-www-form-urlencoded".

Eso es todo. Puedes probar a realizar una o varias llamadas. En la vista principal donde se listan todos los webhooks puedes consultar cuántas llamadas satisfactorias y erróneas se han registrado, así como la hora a la que se registró la última llamada.

Estadísticas

Estadísticas

Ejemplo de configuración y llamada

Esta sería la configuración de tu webhook de entrada, para el caso específico de enviar una campaña con plantilla.

Configuración de ejemplo para enviar campaña con plantilla

Configuración de ejemplo para enviar campaña con plantilla

Una vez el webhook está activo, se muestra un ejemplo de llamada utilizando Postman.

Ejemplo de llamada usando Postman

Ejemplo de llamada usando Postman