Webhooks
Webhooks come in handy for keeping your subscribers in sync. Instead of having to poll our API constantly to check for updates, we'll let you know the instant a change has been made. This might be someone unsubscribing, joining your list, changing their email address and more.
What’s a Webhook?
A webhook is simply a user-defined callback in the form of an HTTP POST, which is invoked when something happens.
For example, when someone subscribes to one of your Campaign Monitor lists, you might like the data about that subscription to be made available to another application. You can do this by simply specifying a URL to which that data should be sent when the subscription occurs.
Using this example of someone subscribing to your list, here’s an example of the data we’ll post in the body of an HTTP POST request to the URL you’ve specified. We can send this to you in either xml
or json
, depending on what’s most useful to you.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"Events": [
{
"CustomFields": [
{
"Key": "website",
"Value": "http://example.org"
}
],
"Date": "2010-12-14 11:32:00",
"EmailAddress": "[email protected]",
"Name": "Test Subscriber",
"SignupIPAddress": "53.78.123.243",
"Type": "Subscribe"
}
],
"ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}
So all you need to do is process this data being received at your URL.
Batching events
To minimise the number of HTTP POST requests we make to your URLs, we batch events together into the request body wherever possible.
For example, if you manually enter two new subscribers through the Campaign Monitor app, we will make one HTTP POST request to your URL, including data similar to the following.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"Events": [
{
"CustomFields": [],
"Date": "2010-12-14 11:32:00",
"EmailAddress": "[email protected]",
"Name": "Test One Subscriber",
"SignupIPAddress": "TypeManual",
"Type": "Subscribe"
},
{
"CustomFields": [],
"Date": "2010-12-14 11:32:00",
"EmailAddress": "[email protected]",
"Name": "Test Two Subscriber",
"SignupIPAddress": "TypeManual",
"Type": "Subscribe"
}
],
"ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}
We’ll batch a maximum of 1,000 events at a time. This means that for an import of a new list containing 6,500 subscribers, you’ll receive a number of POST requests with up to 1,000 subscribe events.
Handling request failures
To ensure we don’t continue to hit a URL that is experiencing a problem, we’ve built some simple failure handling into our webhooks functionality.
If we see sustained errors on a request for more than a week, we will automatically deactivate that webhook for you. This limit is something we’ve set initially, but that may change based on customer feedback if it’s too sensitive. Don’t hesitate to get in touch if you think that’s the case.
Currently available Webhooks
We currently support webhooks on a number of events related to a subscriber list, which are detailed below. We provide the ability to manage subscriber list webhooks using our lists API. The API allows you to create, test, activate, de-activate, and delete webhooks, as well as allowing you to get all webhooks you’ve created for a list.
The data format of the payload we’ll send as the body of the request is always determined by the payload format you specified when creating the webhook (json or xml).
List Subscribe
When someone subscribes to one of your lists, we’ll submit an HTTP POST request similar to the following, to any URLs you’ve registered with the “Subscribe” event.
The “Subscribe” event is triggered in the following ways:
- When subscribers are manually entered on the “Add Subscribers” page
- When subscribers are imported from file
- When subscribers are moved from an inactive state to “Active” on the “Manage Subscriber List” or “Edit Subscriber” pages
- When subscribers subscribe to your list using a subscribe form
- When subscribers are added using the Campaign Monitor API
NOTE: For confirmed opt-in lists, the “Subscribe” event is triggered when the verification link has been clicked in the confirmation email.
POST /subscribe HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/json
{
"Events": [
{
"CustomFields": [
{
"Key": "website",
"Value": "https://example.org"
}
],
"Date": "2010-12-14 11:32:00",
"EmailAddress": "[email protected]",
"Name": "Test Subscriber",
"SignupIPAddress": "53.78.123.243",
"Type": "Subscribe"
}
],
"ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}
Subscriber Update
When a subscriber’s details are updated, we’ll submit an HTTP POST request similar to the following, to any URLs you’ve registered with the “Update” event.
The “Update” event is triggered in the following ways:
- When subscribers have their details updated on the “Edit Subscriber” page
- When existing subscribers are re-imported from file
- When subscribers update their details from the Preference Center
- When existing subscribers are re-added or updated using the Campaign Monitor API
POST /subscribe HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/json
{
"Events": [
{
"CustomFields": [
{
"Key": "website",
"Value": "https://example.org"
}
],
"Date": "2010-12-14 11:32:00",
"OldEmailAddress": "[email protected]",
"EmailAddress": "[email protected]",
"Name": "Test Subscriber Renamed",
"Type": "Update",
"State": "Active"
}
],
"ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}
Subscriber De-activate
When a subscriber in your list is de-activated, we’ll submit an HTTP POST request similar to the following, to any URLs you’ve registered with the “Deactivate” event.
The “Deactivate” event is triggered in the following ways:
- When subscribers are moved to an inactive state on the “Manage Subscriber List” or “Edit Subscriber” pages
- When subscribers unsubscribe by clicking an unsubscribe link
- When subscribers unsubscribe using the Preference Center
- When a spam complaint is reported by a subscriber
- When a hard bounce occurs for a subscriber
- When subscribers are unsubscribed using the Campaign Monitor API
POST /deactivate HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/json
{
"Events": [
{
"CustomFields": [
{
"Key": "website",
"Value": "https://example.org"
}
],
"Date": "2010-12-14 11:32:00",
"EmailAddress": "[email protected]",
"Name": "Test Subscriber",
"Type": "Deactivate",
"State": "Unsubscribed"
}
],
"ListID": "96c0bbdaa54760c8d9e62a2b7ffa2e13"
}
Debugging and testing tools
RequestBin
Before you start building your integration, RequestBin is an excellent low-friction tool for inspecting our live webhook data, without a bunch of setup pain.
ngrok
You’re working furiously on your webhook integration. But webhooks need public URLs, and this isn’t ready for production; you just want to receive calls straight to localhost.
Enter ngrok, a handy utility for setting up tunnels between a server running on localhost and a public URL.
No need to push. Just let ngrok setup a public domain; any traffic will be sent straight through to your local machine. You then create the webhook on that public domain and start handling the webhooks calls locally.