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 quickly and easily. Below is all the information on how to set up and make use of this type of webhooks.
In this article:
- What is an entry webhook?
- Create a new inbound webhook
- Update and delete an inbound webhook
- Steps to perform the integration
What is an entry webhook?
An input webhook is a type of integration that allows you to call Acumbamail from any other external system to execute an operation.
Given a certain set of operations, you can choose one of them and execute it in a way as simple as making an HTTP request of type POST to a dedicated URL generated by client and by operation. This request must include the necessary data to be able 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 in one of the two ways, as 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 done, which is summarized in the table below:
| Characteristic | Inbound webhook | API |
| Authentication | It is transparent. You do not have to add anything to the request, since the url itself that must be called is generated exclusively by client and operation. | You must manually add the account auth_token in each request in order to authenticate. |
| Call | A different url is generated per client and operation. It is necessary to make an HTTP POST request to that url. | Each operation has a fixed and common url for all customers. HTTP POST or GET requests can be made to this. |
| Payload | You can directly send a JSON generated by the external system, since by configuring the webhook you will be able to map the fields that will be in the received JSON and the fields required by the operation. | The system making the call must prepare a payload with a specific format required by the operation. |
| Ease of integration | It does not require programming skills. Many systems allow you to configure automations where the user only has to enter a URL, and the system is responsible for making the call by passing a JSON with specific information. | It is more complex and may require programming skills, as it is necessary to adapt the information that is sent along with the request to a specific format. |
Create a new inbound webhook
Once you have accessed the main view of Inbound Webhooks , you must click on the New webhook button. This will open a popup where you can configure your webhook details:
- Name:A name to identify the webhook.
- Endpoint: Here you will find the list of available operations, from which you must choose one.
- Input Payload:You must copy an example JSON generated by the external system that is going to make the call, since it will serve as a reference to be able to configure the mapping of fields.
- On/Off:Given an input webhook, for Acumbamail to accept the call associated with that webhook, it must be active. If for some reason you don't want to remove the webhook but want to disable it temporarily, you can choose to mark it as non-active (useful for example if you think the URL may have been compromised).
- Field mapping:All the input parameters necessary to be able to execute the operation will be listed. Previously given an example payload (which will be the JSON generated by the external system), you will have a selector where all the nodes present in the JSON are included, so that you can choose which node contains the information associated with each parameter.
When you have entered all the information, you can click the Create button to save the new input webhook.
Once the webhook is created, you must follow a few simple steps so that your integration is ready and operational.
What is the input payload?
The input payload is the parameters or data that the external system will send to Acumbamail when it calls the integration URL. These parameters will contain the information of interest depending on the type of endpoint or operation selected.
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 it is difficult for you to obtain an example of the input parameters that the system from which the call is going to be made to Acumbamail will be sent, you can use a service such as 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 see the parameters, you can copy and paste them into the "input payload" field in Acumbamail.
Finally with the input 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 provided by Acumbamail.
In case it is difficult for you to obtain an example of the input parameters that the system from which the call is going to be made to Acumbamail will be sent, you can use a service such as WebhookSite
What format should the input payload have?
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 are those that correspond to the expected input parameters, depending on the operation chosen.
x-www-form-urlencoded format from Elementor
If you are going to use the input webhook from Elementor, you must take into account the following:
- Use WebhookSite as explained in the previous section to see what Elementor will send.
- You should not copy the "Raw Content" section, but 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:
The "input payload" field in Acumbamail should look like this:
{
"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" } }
}
Available operations
This section describes operations accessible through incoming webhooks.
If you need an additional operation that is present in the API and not as an input 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
This operation allows, given a specific list, to add a subscriber to it.
Required fields
These are the fields associated with the operation:
| Name | Mandatory | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| double_optin | No | Boolean (0,1) Default 0 | Indicates whether or not to send a subscription confirmation email to the list. |
| welcome_email | No | Boolean (0.1) Default 0 | Indicates whether or not to send a welcome email to the subscriber. |
| update_subscriber | No | Boolean (0.1) Default 0 | Indicates whether or not to update the subscriber's information if the subscriber already exists in the list. |
Keep in mind that this operation requires an additional step, by which the webhook is associated with a specific list. An additional selector will appear where you can choose one from all your lists.
This is necessary because each list has different fields that define its subscribers. These fields (apart from those of the operation) also have to be mapped during the configuration of the input webhook, to know in which specific node of the received JSON the information of each field can be located. .
Remove subscriber from a list
This operation allows you to remove a subscriber from a list.
Required fields
These are the fields associated with the operation:
| Name | Mandatory | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| list_id | Yes | Whole number | The identifier of the list to which the subscriber belongs. |
Unsubscribe subscriber from a list
This operation allows you to mark a subscriber in a list as low (unsubscribed).
Required fields
These are the fields associated with the operation:
| Name | Mandatory | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| list_id | Yes | Whole number | The identifier of the list to which the subscriber belongs. |
Send an SMS
This operation allows you to delete a given recipient to a single SMS.
Required fields
These are the fields associated with the operation:
| Name | Mandatory | Expected type | Description |
| body | Yes | Text | The content of the message. |
| recipient | Yes | Phone number | The recipient's phone number (must include prefix). |
| sender | Yes | Text | The name of the sender. |
Send a transactional email
This operation allows you to send an email to a specific subscriber.
Required fields
These are the fields associated with the operation:
| Name | Mandatory | Expected type | Description |
| body | Yes | Text | The content of the email. |
| category | No | Whole number | The category of the shipment. |
| to_email | Yes | Text | The recipient's email address. |
| from_email | Yes | Text | The sender's email address. |
| bcc_email | No | Text | The email address in hidden copy. |
| subject | Yes | Text | The subject of the email. |
Submit a templated campaign
This operation allows you to create and send a campaigns to one or more lists, choosing one of your custom templates as content.
Required fields
These are the fields associated with the operation:
| Name | Mandatory | Expected type | Description |
| name | Yes | Text | The internal name of the campaign. |
| from_name | Yes | Text | The name of the sender. |
| from_email | Yes | Text | The sender's email address. |
| subject | Yes | Text | The subject of the email. |
| lists | Yes | A list of integers | The list of identifiers of the receiving lists. |
| template_id | Yes | Whole number | The id of the template to be used as the content of the email. |
Mapping the lists field
The special case of the "lists" field is highlighted here. In this field you have to pass the identifier of the receiving list or lists of the campaigns. In case there is more than one list, the JSON received must contain a key with a series of identifiers in list format.
Thus, you will be able to see that when you choose a different list, the available fields in the Field Mapping section are updated, adding the fields of the list
| JSON received in the request when invoking the URL | Input payload (copy with quotes) | |
| If you are still not sure how to configure it, you can enter the following as input payload: {"email": ""} and map only this field with the email field of your list. Once done, force a call to the webhook (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. | However, when creating the input webhook, in the input Payload field, you will have to copy your JSON adding quotes to the list. In this way the node containing the lists will be interpreted as a final node containing a value and not an intermediate one. Below is an example JSON (could be in any other format) to illustrate: | |
Return values
In response to a request received, a JSON will always be returned whose content will depend:
- Of the requested operation.
- Whether it was successfully executed or an error occurred.
Response to success
The following table lists the status and JSON content of the response returned for each operation when it was successfully executed.
| Operation | State | JSON | |
| Add subscriber | 201 |
|
|
| Delete subscriber | 201 |
|
|
| Unsubscribe subscriber | 201 |
|
|
| Send SMS | 201 |
|
|
| Send transactional email | 200 |
|
|
| Send templated campaigns | 200 |
|
|
Error response
For any operation, in case of not being able to be executed, a JSON will be returned that will include a descriptive message of the error under the key "error". The following table lists the possible error codes that a callback may return:
| State | Possible reason |
| 400 |
|
| 403 |
|
| 404 |
|
Update and delete an inbound webhook
Given the list of incoming webhooks you've created, in the action menu you can either update a webhook's settings or delete it.
To update the settings of a webhook, you just have to click on the Actions button and there select the Editoption. This will open the popup with all the information associated with the webhook. Here you can make the changes you need, before clicking the Update button to save the changes.
To delete a webhook, you just have to click on the Actions button and select the Delete option. Remember that instead of deleting it, you can also disable a webhook if you temporarily don't need it.
How to perform the integration
Once an input webhook has been created and this is active, it is time to test the integration.
Given the list of created webhooks, click on the Actions button and there select the Copy URL option. This will place the specific URL created for this webhook on the clipboard.
Now you just need to make the configuration on the external system that is going to make the call. Given the event that has to trigger the operation in Acumbamail, you need to configure it as follows:
- You must make an HTTP request of type POST to the URL you just copied. The URL will only respond to REQUESTS of type POST and HEAD.
- In the body of the request 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.
That's all. You can try making one or more calls. In the main view where all the webhooks are listed, you can see how many successful and erroneous calls have been recorded, as well as the time at which the last call was recorded.
Example of configuration and call
This would be the configuration of your inbound webhook, for the specific case of sending a templated campaign.
Once the webhook is active, an example of a call using Postman is displayed.
