incoming webhooks
From the Integrations section (only visible for payment 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 configure and make use of this type of webhooks.
In this article:
- What is a webhook incoming?
- Create a new webhook incoming
- Update and delete a webhook incoming
- Steps to perform the integration
What is a webhook incoming?
A webhook incoming 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.
Webhook incoming vs. API
If an operation is available by API and through an incoming webhook, you will only need to configure the integration in one of the two ways, since the effect will be identical. Both will allow you 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:
| Characteristic | Webhook incoming | 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 webhook incoming
Once you have accessed the main view of inbound Webhooks, click on the New Webhook button. This will open a popup where you can configure the details of your webhook:
- Name:A name to identify the webhook.
- Endpoint: Here you will find the list of available operations, from which you must choose one.
- Payload incoming: 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 a webhook incoming, 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 parameters incoming necessary 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.
Once you have entered all the information, you can click the Create button to save the new webhook incoming.
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 you find it difficult to get an example of the input parameters that will be sent by the system from which the call to Acumbamail will be made, you can make use of 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.
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 the operations accessible through incoming webhooks.
If you need an additional operation that is present in the API and not as a webhook incoming, 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 webhook incoming, to know in which specific node of the received JSON the information of each field can be located. Thus, you will be able to observe that when you choose a different list, the fields available in the Field Mapping section are updated, adding the fields of the list.
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 single SMS to a given recipient.
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 phone number of the recipient (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 campaign templated
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
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 list or lists receiving the campaign. In case it is more than one list, the JSON received must contain a key with a series of identifiers in list format.
However, when creating the webhook incoming, in the Payload incoming field, you will have to copy your JSON by adding quotation marks to the list. In this way the node that contains the lists will be interpreted as an end node that contains a value and not an intermediate one. Below is an example JSON (it could have any other format) to illustrate it:
| JSON received in the request when invoking the URL | Payload incoming (copy with quotation marks) | |
| { "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]" } } |
|
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 campaign with template | 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 a webhook incoming
Given the list of incoming webhooks you've created, in the actions menu you can both update a webhook's settings and 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 there select the Deleteoption. 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 you have created a webhook incoming and being active, it is time to test the integration.
Given the list of webhooks created, click the Actions button and select the Copy URL option. This will place on the clipboard the specific URL created for this webhook.
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 webhook incoming, for the specific case of sending a campaign with template.
Once the webhook is active, an example of a call using Postman is displayed.
