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.

Example of the data in the HTTP POST to your URL on subscription:JSON XML

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"
}

<?xml version="1.0" encoding="utf-8"?>
<Payload>
    <Events>
        <Event>
            <CustomFields>
                <CustomField>
                    <Key>website</Key>
                    <Value>https://example.org</Value>
                </CustomField>
            </CustomFields>
            <Date>2010-12-14 11:32:00</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name>Test Subscriber</Name>
            <SignupIPAddress>53.78.123.243</SignupIPAddress>
            <Type>Subscribe</Type>
        </Event>
    </Events>
    <ListID>96c0bbdaa54760c8d9e62a2b7ffa2e13</ListID>
</Payload>

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 when possible.

For example, if you manually enter two new subscribers through the Campaign Monitor app, we’d make one HTTP POST request to your URL, including data similar to the following.

Batching two subscribe events together in the body of the HTTP POST to your URL:JSON XML

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"
}

<?xml version="1.0" encoding="utf-8"?>
<Payload>
    <Events>
        <Event>
            <CustomFields/>
            <Date>2010-12-14 11:32:00</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name>Test One Subscriber</Name>
            <SignupIPAddress>TypeManual</SignupIPAddress>
            <Type>Subscribe</Type>
        </Event>
        <Event>
            <CustomFields/>
            <Date>2010-12-14 11:32:00</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name>Test Two Subscriber</Name>
            <SignupIPAddress>TypeManual</SignupIPAddress>
            <Type>Subscribe</Type>
        </Event>
    </Events>
    <ListID>96c0bbdaa54760c8d9e62a2b7ffa2e13</ListID>
</Payload>

We’ll batch a maximum of 1,000 events at a time, at the rate of one batch every 10 seconds. This means that for an import of a new list of 6,500 subscribers, over the course of around a minute you’ll receive seven POST requests, the first six with 1,000 subscribe events, and the last with 500.

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.

Request made on list subscribe event:JSON XML

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"
}

POST /subscribe HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<Payload>
    <Events>
        <Event>
            <CustomFields>
                <CustomField>
                    <Key>website</Key>
                    <Value>https://example.org</Value>
                </CustomField>
            </CustomFields>
            <Date>2010-12-14 11:32:00</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name>Test Subscriber</Name>
            <SignupIPAddress>53.78.123.243</SignupIPAddress>
            <Type>Subscribe</Type>
        </Event>
    </Events>
    <ListID>96c0bbdaa54760c8d9e62a2b7ffa2e13</ListID>
</Payload>

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

Request made on subscriber update event:JSON XML

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"
}

POST /subscribe HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<Payload>
    <Events>
        <Event>
            <CustomFields>
                <CustomField>
                    <Key>website</Key>
                    <Value>https://example.org</Value>
                </CustomField>
            </CustomFields>
            <Date>2010-12-14 11:32:00</Date>
            <OldEmailAddress>[email protected]</OldEmailAddress>
            <EmailAddress>[email protected]</EmailAddress>
            <Name>Test Subscriber Renamed</Name>
            <Type>Update</Type>
            <State>Active</State>
        </Event>
    </Events>
    <ListID>96c0bbdaa54760c8d9e62a2b7ffa2e13</ListID>
</Payload>

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

Request made on subscriber deactivate event:JSON XML

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"
}

POST /deactivate HTTP/1.1
Host: example.com:80
Accept: */*
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<Payload>
    <Events>
        <Event>
            <CustomFields>
                <CustomField>
                    <Key>website</Key>
                    <Value>https://example.org</Value>
                </CustomField>
            </CustomFields>
            <Date>2010-12-14 11:32:00</Date>
            <EmailAddress>[email protected]</EmailAddress>
            <Name>Test Subscriber</Name>
            <Type>Deactivate</Type>
            <State>Unsubscribed</State>
        </Event>
    </Events>
    <ListID>96c0bbdaa54760c8d9e62a2b7ffa2e13</ListID>
</Payload>

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.

Our API