Outgoing Webhooks

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

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

What webhooks are for

Webhooks have many uses, the main one is 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 about 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 will receive calls when certain actions occur. You only have to 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 that are used for transactional email and those that are used for campaign sending. In the case of campaigns, the webhook will be configured for each of the lists, as they may come from different databases, thus allowing to configure several webhooks for a campaign, one for each of the lists to which said campaign is sent. The webhooks that are triggered in the case of transactional email will be configured for the entire account. Below is 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. It also indicates in the table which webhooks work only in the campaign service and which in the transactional email service.

Event	It triggers when	Campaigns	Transactional Email
Sign up	A subscriber signs up to a list.	Yes	No
Unsubscribe	A subscriber unsubscribes from a list	Yes	No
Hard bounce	An email is sent to an address that does not exist	Yes	Yes
Complaint	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 configure 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 must go to the Advanced tab.

advanced tab in subscriber list

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

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 subscribers who belong to the list, so you must configure it in each of the lists you want to synchronize.

Configure webhooks for transactional email

To configure the webhooks for transactional email, go to the SMTP section of the left menu 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 lists one, 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 for smtp

Keep in mind that in the transactional email service the events that will be received are fewer, since the event of Subscriber Sign up and Unsubscribe 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 that 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 that we will make. You have to keep in mind that, if your shipping volume is high, you will receive a large number of requests at that URL, so it 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 series of relevant information. Below, we include the information that each type of event contains:

Sign up

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

Unsubscribe

*Parameter*	*Value*
event	unsubscribes
email	The email of the unsubscribed subscriber
timestamp	Date in UNIX timestamp format (in seconds)
campaign_id	Unique identifier of the campaign in which it has unsubscribed
list_id	Unique identifier of the list in which it has been unsubscribed
subscriber_fields	Dictionary in JSON format with the subscriber's fields. 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 for the error

Soft Bounce

*Parameter*	*Value*
event	soft_bounces
email	the subscriber's email
timestamp	Date in UNIX timestamp format (in seconds)

Complaint

*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)