Use webhooks

Webhooks are a mechanism to allow Acumbamail to communicate with an online platform you own. Basically, what you have to do is provide a URL that is able to read the data that Acumbamail will send you when certain events occur. You can choose which events you want to receive to cause less load on your server.

You can make use of webhooks with any of our payment plans.

What are webhooks for?

Webhooks have many utilities, the main one is to maintain synchronization between your database and Acumbamail. They can also be used to learn more about engagement of your emails in your CRM, saving information about which customers open your emails. Basically they are the opposite of API, in a API you can make calls to cause certain actions to occur. In a webhook you will receive calls when certain actions occur. Just create a URL on your web system that allows you to receive the events that Acumbamail will send.

There are two types of webhooks, those used for transactional email and those used for sending campaigns. In the case of campaigns, the webhook will be configured for each of the lists,since they can come from different databases, thus allowing you to configure several webhooks for a campaign, one for each of the lists to which this campaign is sent. The webhooks that are triggered in the case of transactional email will be configured for the entire account. Below you have a list of the events that you can receive in your webhooks, it is not mandatory that you choose all, you can receive only those that are of interest to you. The table also shows which webhooks work only in the campaign service and which in the transactional email service.

event Fires when Campaigns Transactional email
High A subscriber is added to a list. Yes No
Low A subscriber unsubscribes from a list Yes No
Hard bounce An email is sent to an address that does not exist Yes Yes
Complain A recipient marks an email as spam Yes Yes
Opening A recipient opens an email Yes Yes
Click A recipient clicks on an email Yes Yes

Configure webhooks for lists

To set up a webhook in a list you must go to the lists menu within Newsletters and choose one of your lists. Once inside the list itself, you need to go to the Advanced tab.

advanced tab in subscriber listadvanced tab in subscriber list

The webhooks option will be disabled by default, click Configure to start the process. Once this is done, the page will appear before you that will allow you to configure the events that will be sent to your webhooks processing URL. The page is this:

webhooks acumbamail configuration

webhooks acumbamail configuration

In it you must enter the URL of your system that will process the webhooks, it will be the same for all events and you will have to select the events you want to receive. Once this is done, you can activate or deactivate the webhook whenever you want using the button below. Keep in mind that this webhook will only work for the subscribers who belong to the list, so you must configure it in each of the lists that you want to synchronize.

Configure webhooks for transactional email

To configure webhooks for transactional email, go to the SMTP section of the menu on the left and, once SMTP is deployed, you must select the Webhook option:

webhooks menu from transactional email

webhooks menu from transactional email

Once this is done, you will see a page very similar to the list page, which will allow you to enter the URL of your system that will process the webhook and then select the events that will be sent to that URL and activate the webhook:

webhook para smtp

webhook para smtp

Keep in mind that in the transactional email service the events they will receive are fewer, since the Subscriber Registration and Cancellation event does not make sense in this service, as there are no subscribers.

How to process a webhook

When an event occurs, a call will be made to the URL you have configured, a POST request. This URL must be prepared to receive the events, and these will be sent in JSON format, which will be included in the body of the request we will make. You have to keep in mind that, if your volume of shipments is high, you will receive a large number of requests in that URL, so you must be prepared to receive the events correctly.  This JSON object can have one to many events, which will be those that have occurred since the previous request was launched, and will have the following form:

For each event there is a number of relevant information. Below, we include the information contained in each type of event:

High

Parameter Value  
event subscribes  
Email The subscriber's email  
timestamp Date in UNIX timestamp format (in seconds)
 
list_id
Unique identifier of the list to which you have subscribed
subscriber_fields Dictionary in JSON format with the fields of the desubscriptor. E.g, {"email": example@example.com, "name": "Mike"}

Low

Parameter Value  
event unsubscribes  
Email The unsubscribed subscriber's email  
timestamp Date in UNIX timestamp format (in seconds)  
campaign_id Unique identifier of the campaign on which it was desuscrited
list_id Unique identifier of the list in which it was desuscrited
subscriber_fields Dictionary in JSON format with the fields of the desubscriptor. E.g, {"email": example@example.com, "name": "Mike"}

delivered

Parameter Value
event delivered
Email The subscriber's email
timestamp Date in UNIX timestamp format (in seconds)

Hard bounce

Parameter Value
event hard_bounces
Email The subscriber's email
timestamp Date in UNIX timestamp format (in seconds)
bounce_reason Provides the reason why you have given error

Complain

Parameter Value
event complaints
Email The subscriber's email
timestamp Date in UNIX timestamp format (in seconds)

Opening

Parameter Value
event opens
Email The subscriber's email
timestamp Date in UNIX timestamp format (in seconds)

Click

Parameter Value
event clicks
Email The subscriber's email
timestamp Date in UNIX timestamp format (in seconds)