Outbound 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 uses, the main one being to maintain synchronization between your database and Acumbamail. They can also be used to have more information about the engagement of your emails in your CRM, saving information on which customers open your emails. They are basically the opposite of an API, in an API you can make calls to make certain actions occur. In a webhook, you'll receive calls when certain actions occur. All you have to do is create a URL in your web system that allows you to receive the events that Acumbamail is going to 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 to configure several campaigns for a campaign, one for each of the lists to which that campaign is sent. 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 of them, you can receive only the ones that are of interest to you. The table also shows which webhooks work only in the campaign service and which work only in the transactional email service.

Event	Fires when	Bells	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 on a list you must go to the lists menu within Newsletters and choose one of your lists. Once inside the list itself, you must go to the Advanced tab.

advanced 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

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

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

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 to which you unsubscribed
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)