Webhooks de entrada
Desde el apartado de Integraciones (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?
- Crear un nuevo webhook de entrada
- Actualizar y borrar un webhook de entrada
- Pasos para realizar la integración
¿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:
- 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.
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.
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.
Si sigues sin tener claro cómo configurarlo, puedes introducir como payload de entrada lo siguiente: {"email": ""} y mapear solo este campo con el campo email de tu lista. Una vez hecho, fuerza una llamada al webhook (haciendo submit de tu formulario con datos de prueba) y contacta con nuestro equipo de soporte. Ellos podrán revisar la información real recibida en la llamada al webhook e indicarte exactamente cómo debe quedar configurado el campo "payload de entrada".
¿Qué formato debe tener el payload de entrada?
La información se debe enviar en formato 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 desde Elementor
Si vas a usar el webhook de entrada desde Elementor, debes tener en cuenta lo siguiente:
- Usa WebhookSite tal y como se ha explicado en el apartado anterior para ver qué enviará Elementor.
- No debes copiar el apartado de "Raw Content", sino el de "Form values" que es el que tiene el formato esperado, pero incluyendo también los campos "form", "fields" y "meta".
Para el siguiente ejemplo:
El campo "payload de entrada" en Acumbamail debería quedar de la siguiente manera:
{
"form": { "id": "4abdd65", "name": "test" },
"fields": { "name": { "id": "name", "type": "text", "title": "Nome", "value": "test", "raw_value": "test", "required": "0" }, "email": { "id": "email", "type": "email", "title": "Email", "value": "test@test.com", "raw_value": "test@test.com", "required": "1" } },
"meta": { "name": { "id": "1", "year": "2" } }
}
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 |
| Sí | 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.
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.
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 |
| Sí | Texto | La dirección de correo del suscriptor. | |
| list_id | Sí | 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 |
| Sí | Texto | La dirección de correo del suscriptor. | |
| list_id | Sí | 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 | Sí | Texto | El contenido del mensaje. |
| recipient | Sí | Número de teléfono | El número de teléfono del receptor (debe incluir prefijo). |
| sender | Sí | 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 | Sí | Texto | El contenido del email. |
| category | No | Número entero | La categoría del envío. |
| to_email | Sí | Texto | La dirección de correo del receptor. |
| from_email | Sí | Texto | La dirección de correo del emisor. |
| bcc_email | No | Texto | La dirección de correo en copia oculta. |
| subject | Sí | 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 | Sí | Texto | El nombre interno de la campaña. |
| from_name | Sí | Texto | El nombre del emisor. |
| from_email | Sí | Texto | La dirección de correo del emisor. |
| subject | Sí | Texto | El asunto del email. |
| lists | Sí | Una lista de número enteros | La lista de identificadores de las listas receptoras. |
| template_id | Sí | 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 |
|
|
| Borrar suscriptor | 201 |
|
|
| Desuscribir suscriptor | 201 |
|
|
| Enviar SMS | 201 |
|
|
| Enviar email transaccional | 200 |
|
|
| Enviar campaña con plantilla | 200 |
|
|
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 |
|
| 403 |
|
| 404 |
|
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.
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.
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.
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.
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.
Una vez el webhook está activo, se muestra un ejemplo de llamada utilizando Postman.
