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?

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:

How to access incoming webhooks

How to access incoming webhooks

  • 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.

Form to create input webhook

When you have entered all the information, you can click the Create button to save the new input webhook.

New webhook created

New webhook created

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:

Result of calling webhook.site from Elementor

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
email 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.

List selector in which to subscribe the subscriber

List selector in which to subscribe the subscriber

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. .

Example fields to map from a specific list

Example fields to map from a specific 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
email 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
email 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
  • id: It is the unique identifier of the subscriber.
  • email: The subscriber's email address.
Delete subscriber
201
  • email: The subscriber's email address
Unsubscribe subscriber
201
  • Empty JSON
Send SMS
201
  • id: It is the unique identifier of the SMS sent
Send transactional email
200
  • key: It is a unique identifier of the email sent
Send templated campaigns
200
  • id: This is the unique identifier of the campaign




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
  • Any of the received parameters do not contain a valid value, or
  • The mapping has been misconfigured and any of the parameters could not be located in the received JSON.
403
  • Access denied because the user has upgraded from a paid plan to a free plan, or
  • Access denied because the requested input webhook is disabled.
404
  • Some of the parameters received refer to an element that does not exist (subscriber, list, etc.), or
  • The URL cannot be associated with any input webhook.


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.

Edit an existing webhook

Edit an existing webhook

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.

Delete a webhook

Delete a webhook

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.

How to copy the integration url

How to copy the integration url

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.

Statistics

Statistics

Example of configuration and call

This would be the configuration of your inbound webhook, for the specific case of sending a templated campaign.

Sample configuration for sending templated campaigns

Sample configuration for sending templated campaigns

Once the webhook is active, an example of a call using Postman is displayed.

Call example using Postman

Call example using Postman