Webhooks incoming

From the Developers 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 simple way. 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?

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:

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

Form to create webhook incoming

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

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

Acumbamail currently supports these two formats: JSON and x-www-form-urlencoded. However, you will find it easier to configure the mapping if the data is sent in JSON, so if during the configuration of the integration you can choose between several formats, we recommend you choose the JSON.

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.

Format x-www-form-urlencoded

On the other hand, if the data is sent in x-www-form-urlencoded format, you must transform this information to JSON format before copying it into the "input payload" field. The following is an example of how to transform data sent as x-www-form-urlencoded:

 x-www-form-urlencoded JSON
Fecha+de+nacimiento=24%2F10%2F1972
&Lugar+de+nacimiento=Madrid
&Email=test%40test.com
&Date=19%2F10%2F2022&Time=06%3A01
&User+Agent=Mozilla%2F5.0+%28Windows+NT+10.0%3B+Win64%3B+x64%29
&Remote+IP=127.0.0.1&Powered+by=Elementor
&form_id=1234&form_name=Mi+formulario
{
    "Date": "19/10/2022",
    "Email": "test@test.com",
    "Fecha de nacimiento": "24/10/1972",
    "Lugar de nacimiento": "Madrid",
    "Powered by": "Elementor",
    "Remote IP": "127.0.0.1",
    "Time": "06:01",
    "User Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "form_id": "1234",
    "form_name": "Mi formulario"
}

fields%5Bname%5D%5Btype%5D=text&fields%5Bname%5D%5Bvalue%5D=Test&
fields%5Bname%5D%5Brequired%5D=1&fields%5Bemail%5D%5Btype%5D=email&
fields%5Bemail%5D%5Bvalue%5D=test@test.com&fields%5Bemail%5D%5Brequired%5D=1
{
    "fields[name][value]": "Test",
    "fields[name][required]": "1", 
    "fields[name][type]": "text",
    "fields[email][required]": "1", 
    "fields[email][type]": "email",  
    "fields[email][value]": "test@test.com"
}

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

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 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
  • 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 campaign with template 200
  • id: It 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 webhook incoming 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 webhook incoming.

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.

Edit an existing webhook

Edit an existing webhook

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.

Delete a webhook

Delete a webhook

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.

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 webhook incoming, for the specific case of sending a campaign with template.

Sample settings for sending templated campaign

Sample settings for sending templated campaign

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

Call example using Postman

Call example using Postman