What is a webhook?
A Mailercloud webhook is a mechanism that allows external systems to receive real-time updates and notifications about events occurring within your mailercloud account. When specific events or triggers occur within your account, such as the delivery of an email campaign or the opening of an email by a recipient, the webhook sends instant notifications to predefined URLs or endpoints you desire.
Webhooks are widely used nowadays as they are key to allowing multiple systems to interconnect and keep actions consistent among them. They are also known as "URL Callbacks" or "HTTP push calls".
A webhook is a way for different systems to communicate with each other in real time. When an event or status change occurs in a system, an HTTP POST request is sent to the given URL in real time. This POST call contains information related to that specific event, such as the time it occurred, the name of the event, and key identifiers.
To set up a webhook, you will need to define a notification URL or endpoint on your side where the event data will be pushed on behalf of Mailercloud whenever it's triggered.
Webhook URL Format
The webhook URL serves as the endpoint where the HTTP POST request will be sent when a specific event or status change occurs. It should be a valid and accessible URL that can receive incoming requests.
It is important to note that only URLs with the HTTP or HTTPS protocol are accepted for webhook URLs. This ensures secure and reliable communication between systems.
For example, if you have a webhook set up to receive notifications for campaign events, such as campaign sent or campaign opened, the webhook URL should be provided in the correct format, such as http://example.com or https://example.com.
How to create a webhook in Mailercloud
To create a webhook in Mailercloud, please follow these steps:
Login to your Mailercloud account.
Go to the "Accounts" section.
Select "Integrations" and choose "Webhooks".
Click the "Create Your First Webhook" button.
5. Fill in the required information in the "Create New Webhook" page and select create.
6. Once created, you can manage your webhooks on the webhook listing page. From there, you can edit the webhook settings,test webhook, send sample data, deactivate or delete the webhooks as needed.
7. If you want to create additional webhooks, simply follow the same steps for each new webhook.
Event Triggers
Webhooks can be triggered by the following triggered events: send, open, click, fail, spam, unsubscribe and bounce. Let’s explore each of the events with some examples.
1. Sent Event
Here is an example of the payload for the "Sent Event" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Campaign Sent",
"emails": ["sample@gmail.com", "sample2@gmail.com"],
"campaign_name": "Sample Campaign",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"date_sent": "2024-01-01 01:30:00",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Campaign Sent".
emails: An array of email addresses that were sent the campaign.
campaign_name: The name of the campaign that was sent.
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
date_sent: The date and time when the campaign was sent.
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
Note: This trigger is sent as a batch of 1000. Therefore, if 10,000 emails are sent, it will result in 10 triggers, with each trigger containing 1000 emails.
2. Open Event
Here is an example of the payload for the "Opened" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Opened",
"email": "sample@gmail.com",
"campaign_name": "Sample Campaign",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"date_event": "2024-01-01 01:30:00",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Opened".
email: The email address of the recipient who opened the email.
campaign_name: The name of the campaign associated with the opened event.
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
date_event: The date and time when the event (opening) occurred.
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
3. Click Event
Here is an example of the payload for the "Clicked" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Clicked",
"email": "sample@gmail.com",
"campaign_name": "Sample Campaign",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"URL": "clicked_url.com",
"date_event": "2024-01-01 01:30:00",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Clicked".
email: The email address of the recipient who clicked on the link.
campaign_name: The name of the campaign associated with the clicked event.
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
URL: The URL that was clicked by the recipient.
date_event: The date and time when the event (clicking) occurred.
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
4. Fail Event
Here is an example of the payload for the "Campaign Failed" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Campaign Failed",
"campaign_name": "Sample Campaign",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"date_event": "2024-01-01 01:30:00",
"reason": "No sender id",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Campaign Failed".
campaign_name: The name of the campaign that failed to deliver.
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
date_event: The date and time when the failure event occurred.
reason: Provides the reason for the failure, in this example, it is "No sender id".
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
5. Spam Event
Here is an example of the payload for the "Spam" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Spam",
"email": "sample@gmail.com",
"campaign_name": "Sample Campaign",
"reason": "undesired",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"date_event": "2024-01-01 01:30:00",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Spam".
email: The email address of the recipient who marked the email as spam.
campaign_name: The name of the campaign associated with the spam event.
reason: Provides the reason or description for marking the email as spam, in this example, it is "undesired".
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
date_event: The date and time when the spam event occurred.
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
6. Unsubscribe Event
Here is an example of the payload for the "Unsubscribed" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Unsubscribed",
"email": "sample@gmail.com",
"campaign_name": "Sample Campaign",
"list_id": "def",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"date_event": "2024-01-01 01:30:00",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Unsubscribed".
email: The email address of the recipient who unsubscribed from the campaign.
campaign_name: The name of the campaign from which the recipient unsubscribed.
list_id: The unique identifier of the list from which the recipient unsubscribed.
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
date_event: The date and time when the unsubscription event occurred.
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
7. Bounce Event
Here is an example of the payload for the "Bounced" webhook trigger, along with a brief explanation of each parameter:
{
"event": "Bounced",
"email": "sample@gmail.com",
"campaign_name": "Sample Campaign",
"tag_name": "Sample Tag",
"campaign_id": "abc",
"date_event": "2024-01-01 01:30:00",
"reason": "email doesn't exist",
"ts": 1604937111,
"ts_event": 1604937111
}
event: Indicates the type of event, in this case, it is "Bounced".
email: The email address that bounced.
campaign_name: The name of the campaign associated with the bounce event.
tag_name: The tag associated with the campaign.
campaign_id: The unique identifier of the campaign.
date_event: The date and time when the bounce event occurred.
reason: Describes the reason for the bounce, in this example, it is "email doesn't exist".
ts: A timestamp representing the date and time in Unix format.
ts_event: A timestamp specifically for the event, also in Unix format.
Webhook Limits
Plan-wise Limits
Free Plan: Users can create up to 20 webhooks.
Premium and Enterprise Plans: Users can create up to 50 webhooks.
Daily Trigger Limits
Free Plan: Users can trigger a maximum of 10,000 events per day.
Premium and Enterprise Plans: Users have the flexibility of triggering an unlimited number of events per day.
Retry Mechanism:
In the event of a webhook delivery failure, a retry mechanism will be activated with the following configuration:
Number of Retries: 3 times
This retry mechanism ensures that in case of any temporary delivery issues, the system will automatically attempt to resend the webhook payload up to three times. The retries are triggered when the response from the webhook URL is not 200, 201, or 204 (indicating a successful delivery), or in cases of timeouts. The retry time interval is set to 10 seconds between each attempt, allowing for improved reliability of event delivery.
Automatic Deactivation:
If a webhook experiences 20 consecutive failed delivery attempts, it will be automatically deactivated. Once deactivated, triggers will not be sent to the specified URL. Manual reactivation is required to resume webhook functionality.
An email notification will be sent to the registered account when a webhook is automatically deactivated. The email will include details such as the URL of the deactivated webhook and the reason for deactivation. It's important to note that deactivation prevents any further delivery of triggers until manual reactivation is completed.
FAQ
1. What is a webhook?
Webhooks are widely used to allow multiple systems to interconnect and maintain consistency in their actions. They are also known as "URL Callbacks" or "HTTP push calls." A webhook facilitates real-time communication between different systems by sending an HTTP POST request to a specified URL when a particular event or status change occurs.
2. What are the event triggers for webhooks?
Webhooks can be triggered by events such as send, open, click, fail, spam, unsubscribe, and bounce, each with specific payload examples representing the data sent when the event is triggered.
3. What are the limits for webhooks in Mailercloud?
In the Free Plan, users can create up to 20 webhooks, while Premium and Enterprise Plans allow up to 50. Additionally, Free Plan users can trigger a maximum of 10,000 events per day, while Premium and Enterprise Plans allow unlimited event triggers per day.
4. How does automatic deactivation work for webhooks?
If a webhook experiences 20 consecutive failed delivery attempts, it will be automatically deactivated. Manual reactivation is required to resume webhook functionality, and an email notification will be sent with details about the deactivation and the reason for it.
5. Where can I find the webhook API?
You can find the webhook API here.