Incoming Webhooks
From the Integrations section (visible only for paid accounts), you can set up a series of incoming webhooks. These provide an additional way to integrate external systems with Acumbamail quickly and easily. Below is all the information on how to configure and use this type of webhook.
In this article:
- What is an incoming webhook?
- Create a new incoming webhook
- Update and delete an incoming webhook
- Steps to perform the integration
What is an incoming webhook?
An incoming webhook is a type of integration that allows you to call Acumbamail from any other external system to execute an operation.
Given a specific set of operations, you can choose one of them and execute it as simply as making a POST HTTP request to a dedicated URL generated by client and operation. This request must include the necessary data to execute the operation in the body, in JSON format.
Incoming webhook vs. API
If an operation is available via API and through an incoming webhook, you only need to configure the integration through one of the two methods, as the effect will be identical. Both will allow you to call Acumbamail to execute a specific operation. However, the difference lies in how the integration is performed, which is summarized in the following table:
| Feature | Incoming Webhook | API |
| Authentication | It is transparent. Nothing needs to be added to the request, as the URL to call is generated exclusively by client and operation. | The auth_token of the account must be manually added to each request to authenticate. |
| Call | A different URL is generated for each client and operation. It is necessary to make a POST HTTP request to that URL. | Each operation has a fixed and common URL for all clients. HTTP POST or GET requests can be made to this. |
| Payload | You can directly send a JSON generated by the external system, as when configuring the webhook you can 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 | Does not require programming skills. Many systems allow configuring automations where the user only needs to enter a URL, and the system takes care of making the call passing a JSON with specific information. | It is more complex and may require programming skills, as it is necessary to adapt the information sent with the request to a specific format. |
Create a new incoming webhook
Once you have accessed the main view of Incoming Webhooks, you need to 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.
- Incoming payload: You must 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 required input parameters to execute the operation will be listed. Given a sample 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 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 incoming webhook.
Once the webhook is created, you must follow a few simple steps to get your integration ready and operational.
What is the incoming payload?
The incoming payload consists of 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 incoming payload?
This depends on the external system you want to integrate with Acumbamail. Some allow you to view a sample of the information that will be sent or even configure different options to format the data that will be sent in the request. However, others do not directly provide this information.
If you find it difficult to obtain a sample of the input parameters that the system making the call to Acumbamail will 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 "incoming payload" field in Acumbamail.
Finally, with the incoming webhook already created in Acumbamail, you will only need to change the integration you previously configured in the external system, so that instead of calling the test URL, it calls the real URL provided by Acumbamail.
If you are still unclear on how to configure it, you can enter the following as the incoming 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 "incoming payload" field should be configured.
What format should the incoming payload have?
The information must be sent in JSON format.
JSON Format
If the data is sent in JSON format, you only need to copy a sample of the parameters sent with the call in the "incoming 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
If you are going to use the incoming webhook from Elementor, you should keep the following in mind:
- 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 has the expected format, but also includes the "form", "fields", and "meta" fields.
For the following example:
The "incoming payload" field in Acumbamail should look like this:
{
"form": { "id": "4abdd65", "name": "test" },
"fields": { "name": { "id": "name", "type": "text", "title": "Name", "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 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 a 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 | Required | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| double_optin | No | Boolean (0,1) Default 0 | Indicates whether to send a subscription confirmation email to the list. |
| welcome_email | No | Boolean (0,1) Default 0 | Indicates whether to send a welcome email to the subscriber. |
| update_subscriber | No | Boolean (0,1) Default 0 | Indicates whether to update the subscriber's information if they already exist in the list. |
It should be noted that this operation requires an additional step, whereby 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 (in addition to those specific to the operation) must also be mapped during the configuration of the incoming webhook, to know in which specific node of the received JSON the information for each field can be located. Thus, you will 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.
Delete a 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 | Required | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| list_id | Yes | Integer | The identifier of the list to which the subscriber belongs. |
Unsubscribe a subscriber from a list
This operation allows you to mark a subscriber as unsubscribed from a list.
Required fields
These are the fields associated with the operation:
| Name | Required | Expected type | Description |
| Yes | Text | The subscriber's email address. | |
| list_id | Yes | Integer | The identifier of the list to which the subscriber belongs. |
Send an SMS
This operation allows you to send a single SMS to a given recipient.
Required fields
These are the fields associated with the operation:
| Name | Required | 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 | Required | Expected type | Description |
| body | Yes | Text | The content of the email. |
| category | No | Integer | The category of the sending. |
| 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 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
These are the fields associated with the operation:
| Name | Required | 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 recipient lists. |
| template_id | Yes | Integer | The identifier of the template that will be used as the content of the email. |
Mapping the lists field
Here we highlight the special case of the "lists" field. In this field, you need to pass the identifier of the list or lists receiving the campaign. If it is more than one list, the received JSON must contain a key with a series of identifiers in list format.
However, when creating the incoming webhook, in the Incoming payload field, you will need to copy your JSON adding quotes to the list. This way, the node that contains the lists will be interpreted as a final node that contains a value and not an intermediate one. Below is an example JSON (it could have any other format) to illustrate this:
| JSON received in the request when invoking the URL | Incoming payload (copy with quotes) | |
| { "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 received request, a JSON will always be returned whose content will depend on:
- The requested operation.
- Whether it was successfully executed or an error occurred.
Success response
The following table summarizes the status and the content in JSON format of the response returned for each operation when it has been successfully executed.
| Operation | Status | 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, if it cannot be executed, a JSON will be returned that will include a descriptive error message under the key "error". The following table includes the possible error codes that a call may return:
| Status | Possible reason |
| 400 |
|
| 403 |
|
| 404 |
|
Update and delete an incoming webhook
Given the list of incoming webhooks you have created, in the actions menu you can both update the configuration of a webhook and delete it.
To update the configuration of a webhook, you just need to click 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 the changes you need before clicking the Update button to save the changes.
To delete a webhook, you just need to click the Actions button and select the Delete option. Remember that instead of deleting it, you can also deactivate a webhook if you temporarily do not need it.
How to perform the integration
Once an incoming webhook is created and active, it is time to test the integration.
Given the list of created webhooks, click the Actions button and select the Copy URL option. This will place the specific URL created for this webhook in the clipboard.
Now you just need to configure the external system that will make the call. Given the event that needs to trigger the operation in Acumbamail, you should configure it as follows:
- It must make a POST HTTP request to the URL you just copied. The URL will only respond to POST and HEAD requests.
- In the body of the request, it 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 it. You can try making one or several calls. In the main view where all the webhooks are listed, you can check how many successful and erroneous calls have been recorded, as well as the time the last call was recorded.
Example of configuration and call
This would be the configuration of your incoming webhook, for the specific case of sending a campaign with a template.
Once the webhook is active, an example of a call using Postman is shown.
