Outbound Webhooks
Webhooks are a mechanism to allow Sendarmy 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 Sendarmy 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 Sendarmy. They can also be used to learn more about the engagement of your emails in your CRM, saving information about which customers open your emails. Basically, they are the opposite of API, in an 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 Sendarmy 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 emails 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.
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:
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:
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:
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 too 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 | |
| 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”: [email protected], “name”: “Mike”} | |
Low
| Parameter | Value | |
| event | unsubscribes | |
| 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”: [email protected], “name”: “Mike”} | |
delivered
| Parameter | Value | |
| event | delivered | |
| The subscriber’s email | ||
| timestamp | Date in UNIX timestamp format (in seconds) | |
Hard bounce
| Parameter | Value |
| event | hard_bounces |
| The subscriber’s email | |
| timestamp | Date in UNIX timestamp format (in seconds) |
| bounce_reason | Provides the reason why you have given an error |
Complain
| Parameter | Value |
| event | complaints |
| The subscriber’s email | |
| timestamp | Date in UNIX timestamp format (in seconds) |
Opening
| Parameter | Value |
| event | opens |
| The subscriber’s email | |
| timestamp | Date in UNIX timestamp format (in seconds) |
Click
| Parameter | Value |
| event | clicks |
| The subscriber’s email | |
| timestamp | Date in UNIX timestamp format (in seconds) |
Last updated on November 23, 2022