Incoming webhooks
From the Integrations section (only visible for paid accounts), you can configure a series of incoming webhooks. These are an additional way to integrate external systems with Acumbamail in a quick and easy way. Below is all the information on how to configure and use this type of webhooks.
In this article:
- What is an inbound webhook?
- Create a new inbound webhook
- Updating and deleting an incoming webhook
- Steps to perform the integration
What is an inbound webhook?
You must make an HTTP POST request to the URL you just copied. The URL will only respond to POST and HEAD requests.
Given a set of operations, you can choose one of them and execute it in a simple way by making a POST HTTP request to a dedicated URL generated per client and per operation. This request must include the data necessary to execute the operation in the body, in JSON format.
Inbound Webhook vs. API
If an operation is available via API and through an incoming webhook, you will only need to configure the integration via one of the two ways, since the effect will be identical. Both will allow you to do the same thing, call Acumbamail to execute a certain operation. However, the difference lies in the way the integration is performed, which is summarized in the following table:
| Feature | Inbound Webhook | API |
| Authentication | It is transparent. Nothing needs to be added to the request, since the URL to be called is generated exclusively for each client and operation. | Use WebhookSite as explained in the previous section to see what Elementor will send. |
| Call | Each operation has a fixed URL that is common to all clients. HTTP POST or GET requests can be made to this URL. | An inbound webhook is a type of integration that allows you to call Acumbamail from any other external system to execute an operation. |
| Payload | Please note that this operation requires an additional step, which is to associate the webhook with a specific list. An additional selector will appear where you can choose one from all your lists. | The mapping has been misconfigured and some of the parameters in the received JSON could not be located. |
| Ease of integration | Once you have accessed the main Inbound Webhooks view, you need to click on the New Webhook button. This will open a popup where you can configure the details of your webhook: | It is more complex and may require programming skills, as the information sent with the request needs to be adapted to a specific format. |
Create a new inbound webhook
You can directly send a JSON generated by the external system, since when configuring the webhook you will be able to map the fields that will be found in the received JSON and the fields required by the operation.
- Name : A name to identify the webhook.
- Indicates whether or not to update the subscriber's information if the subscriber already exists in the list.
- Input payload : You will need to copy a sample JSON generated by the external system that will make the call, as it will serve as a reference to configure the field mapping.
- Enabled/Disabled : Given an incoming webhook, for Acumbamail to accept the call associated with that webhook, it must be active. If for some reason you do not want to delete the webhook but want to temporarily disable it, you can choose to mark it as inactive (useful for example if you think the URL may have been compromised).
- Field mapping : All the input parameters required to execute the operation will be listed. Given a previous example payload (which will be the JSON generated by the external system), you will have a selector that includes all the nodes present in the JSON, so that you can choose which node contains the information associated with each parameter.
The following table shows the status and the content in JSON format of the response returned for each operation when it has been successfully executed.
A different URL is generated per client and operation. An HTTP POST request must be made to that URL.
What is input payload?
For any operation, if it cannot be executed, a JSON will be returned that will include a descriptive error message under the "error" key. The following table includes the possible error codes that a call can return:
How do I find out the input payload?
This depends on the external system you want to integrate with Acumbamail. Some allow you to view an example of the information to be sent or even configure different options to format the data to be sent in the request. However, others do not directly provide this information.
In case you find it difficult to get an example of the input parameters that the system from which the call is going to be made to Acumbamail is going to send, you can use a service like WebhookSite . This generates a test URL that you can call from your external system and will allow you to view the parameters received in the test call. Once you view the parameters, you can copy and paste them into the "input payload" field in Acumbamail.
Given a set of operations, you can choose one of them and execute it in a simple way by making a POST HTTP request to a dedicated URL generated per client and per operation. This request must include the data necessary to execute the operation in the body, in JSON format.
If you're still not sure how to set this up, you can enter the following as the input payload: {"email": ""} and map only this field to your list's email field. Once done, force a webhook call (by submitting your form with test data) and contact our support team. They will be able to review the actual information received in the webhook call and tell you exactly how the "input payload" field should be configured.
message_id : It is a unique identifier of the email sent
The information must be sent in JSON format.
JSON format
If the data is sent in JSON format, you will only have to copy an example of the parameters that are sent with the call in the "input payload" field and once copied, select in the "field mapping" section which nodes of the JSON correspond to the expected input parameters, depending on the chosen operation.
x-www-form-urlencoded format from Elementor
Once an inbound webhook has been created and is active, it is time to test the integration.
- The calling system must prepare a payload with a specific format required by the operation.
- You should not copy the "Raw Content" section, but rather the "Form values" section, which is the one with the expected format, but also including the "form", "fields" and "meta" fields.
For the following example:
This operation allows you to mark a subscriber as unsubscribed from a list.
{
email : The subscriber's email address
No programming skills required. Many systems allow you to set up automations where the user only has to enter a URL, and the system takes care of making the call by passing a JSON with specific information.
The identifier of the list to which the subscriber belongs.
}
Available operations
This section describes the operations accessible through incoming webhooks.
If you require an additional operation to be present in API and not as an incoming webhook, you can contact the support team and request its inclusion. Your request will be evaluated and the new operation may be added.
Add subscriber to a list
Whether it was successfully executed or whether an error occurred.
Required fields
List selector to subscribe the subscriber to
| Name | Mandatory | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| double_optin | No | Boolean (0,1) Default 0 | The "input payload" field in Acumbamail should look like this: |
| welcome_email | No | Boolean (0,1) Default 0 | This operation allows you to remove a subscriber from a list. |
| update_subscriber | No | Boolean (0,1) Default 0 | The account's auth_token must be manually added to each request in order to authenticate. |
To delete a webhook, simply click on the Actions button and select the Delete option. Remember that instead of deleting it, you can also disable a webhook if you don't need it temporarily.
This is necessary because each list has different fields that define its subscribers. These fields (apart from those specific to the operation) also have to be mapped during the configuration of the input webhook, in order to know in which specific node of the received JSON the information for each field can be located. Thus, you will be able to observe that when you choose a different list, the available fields in the Field Mapping section are updated, adding the fields specific to the list.
Remove subscriber from a list
The URL cannot be associated with any inbound webhook.
Required fields
List selector to subscribe the subscriber to
| Name | Mandatory | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| list_id | Yes | Integer | The ID of the template to use as the email content. |
Unsubscribe subscriber from a list
In response to a received request, a JSON will always be returned whose content will depend on:
Required fields
List selector to subscribe the subscriber to
| Name | Mandatory | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| list_id | Yes | Integer | The ID of the template to use as the email content. |
Send a text message
This operation allows you to delete a single SMS to a given recipient.
Required fields
List selector to subscribe the subscriber to
| Name | Mandatory | Expected type | Description |
| body | Yes | Text | The content of the message. |
| recipient | Yes | Phone number | The phone number of recipient (must include prefix). |
| sender | Yes | Text | The name of the issuer. |
Send a transactional email
Access is denied because the requested inbound webhook is disabled.
Required fields
List selector to subscribe the subscriber to
| Name | Mandatory | Expected type | Description |
| body | Yes | Text | The content of the email. |
| category | No | Integer | The category of the shipment. |
| to_email | Yes | Text | The email address of recipient. |
| from_email | Yes | Text | The sender's email address. |
| bcc_email | No | Text | The email address in blind copy. |
| subject | Yes | Text | The subject of the email. |
Send a campaign with a template
This operation allows you to create and send a campaign to one or more lists, choosing one of your custom templates as content.
Required fields
List selector to subscribe the subscriber to
| Name | Mandatory | Expected type | Description |
| name | Yes | Text | The internal name of the campaign. |
| from_name | Yes | Text | The name of the issuer. |
| from_email | Yes | Text | The sender's email address. |
| subject | Yes | Text | The subject of the email. |
| lists | Yes | A list of integers | These are the fields associated with the operation: |
| template_id | Yes | Integer | This operation allows, given a specific list, to add a subscriber to it. |
Mapping the lists field
The special case of the "lists" field is highlighted here. In this field, the identifier of the list or lists receiving the campaign must be passed. If there is more than one list, the JSON received must contain a key with a series of identifiers in list format.
However, when creating the input webhook, in the Input Payload field, you will need to copy your JSON by adding quotes to the list. This way the node containing the lists will be interpreted as an end node containing a value and not an intermediate one. Here is an example JSON (it could be in any other format) to illustrate this:
| This operation allows you to send an email to a specific subscriber. | Input payload (copy with quotes) | |
| This depends on the external system you want to integrate with Acumbamail. Some allow you to view an example of the information to be sent or even configure different options to format the data to be sent in the request. However, others do not directly provide this information. | Enabled/Disabled : Given an incoming webhook, for Acumbamail to accept the call associated with that webhook, it must be active. If for some reason you do not want to delete the webhook but want to temporarily disable it, you can choose to mark it as inactive (useful for example if you think the URL may have been compromised). | |
Return values
Endpoint : Here you will find the list of available operations, from which you must choose one.
- Of the requested operation.
- Access denied because the user has been upgraded from a paid plan to a free plan, or
Response to success
It is more complex and may require programming skills, as the information sent with the request needs to be adapted to a specific format.
| Operation | State | ||
| Add subscriber | 201 |
|
|
| Delete subscriber | 201 |
|
|
| Unsubscribe subscriber | 201 |
|
|
| Send SMS | 201 |
|
|
| Send transactional email | 200 |
|
|
| Send campaign with template | 200 |
|
|
Error response
That's it. You can try making one or more calls. In the main view where all webhooks are listed, you can see how many successful and failed calls have been registered, as well as the time at which the last call was registered.
| State | Possible reason |
| 400 |
|
| 403 |
|
| 404 |
|
Updating and deleting an incoming webhook
Given the list of incoming webhooks you've created, in the actions menu you can either update a webhook's configuration or delete it.
To update the settings of a webhook, simply click on the Actions button and select the Edit option. This will open the popup with all the information associated with the webhook. Here you can make any changes you need, before clicking on the Update button to save the changes.
The input payload is the parameters or data that the external system will send to Acumbamail when calling the integration URL. These parameters will contain the information of interest depending on the type of endpoint or operation selected.
How to perform the integration
Once you've created your webhook, you need to follow a few simple steps to get your integration up and running.
Given the list of created webhooks, click on the Actions button and select the Copy URL option. This will place the specific URL created for this webhook on the clipboard.
Now you just need to configure the external system that will make the call. Given the event that has to trigger the operation in Acumbamail, you must configure it as follows:
- In the request body you must send the generated information, preferably as a raw JSON, whose content type would be " application/json; charset=utf-8 ". The content type " application/x-www-form-urlencoded " is also supported.
- In the request body you must send the generated information, preferably as a raw JSON, whose content type would be " application/json; charset=utf-8 ". The content type " application/x-www-form-urlencoded " is also supported.
Finally, with the incoming webhook already created in Acumbamail, you will only have to change the integration that you have previously configured in the external system, so that instead of calling the test URL, it calls the real URL that Acumbamail provides you.
Configuration and call example
This would be the configuration of your incoming webhook, for the specific case of sending a campaign with a template.
One of the parameters received refers to an element that does not exist (subscriber, list, etc.), or
