Webhooks

With Webhooks, you can collect information about audience changes as they happen in Mailchimp. After entering a valid URL, you can then choose the type of updates you want to receive.

This guide explains how to configure webhooks directly in your Mailchimp account and how to do it using the API so you can get updates instantly.

Create a webhook in your Mailchimp account

To create a webhook in your Mailchimp account, follow these steps.

Log into Mailchimp, and then navigate to the Audience page.
Select the drop-down menu next to the audience you want to work with, and then choose Settings.
On the Settings page, click Webhooks.
Click Create New Webhook.
In the Callback URL field, type the URL from the integration or application where you want to send webhook requests. This URL will receive data about your Mailchimp audience
Select the boxes next to each update type to choose the events that will trigger your webhook.
Click Save.

The webhook will notify your application of any events.

Create a webhook using the API

To learn how to configure webhooks using the API, refer to the Webhooks reference guide.

For general information about webhooks, visit PBWiki Webhooks.

How it works

When a webhook triggers based on your configured settings, Mailchimp sends an HTTP POST request to the URL you specified. If the URL is unavailable or takes more than 10 seconds to respond, the request is canceled and the system will try again later. Retries happen at increasing intervals over the course of one hour and 15 minutes. Excessive or unresponsive webhook requests may be dropped or disabled at Mailchimp's discretion.

Different data is returned based on each event. Below is sample data for each event. (You can also see this using the RequestBin tool.) Generally speaking, each event has a type and a fired_at field so you can track the type of event and get a timestamp (in GMT) for the event.

The example below shows the fields returned - the POST request actually sends key/value pairs, just like a normal HTML form submission.

Subscribes

"type": "subscribe",
"fired_at": "2009-03-26 21:35:57",
"data[id]": "8a25ff1d98",
"data[list_id]": "a6b5da1054",
"data[email]": "api@mailchimp.com",
"data[email_type]": "html",
"data[merges][EMAIL]": "api@mailchimp.com",
"data[merges][FNAME]": "Mailchimp",
"data[merges][LNAME]": "API",
"data[merges][INTERESTS]": "Group1,Group2",
"data[ip_opt]": "10.20.10.30",
"data[ip_signup]": "10.20.10.30"

Unsubscribes

An event's action is either unsub or delete. The reason will be manual unless caused by a spam complaint, then it will be abuse.

"type": "unsubscribe",
"fired_at": "2009-03-26 21:40:57",  
"data[action]": "unsub",
"data[reason]": "manual",
"data[id]": "8a25ff1d98",
"data[list_id]": "a6b5da1054",
"data[email]": "api+unsub@mailchimp.com",
"data[email_type]": "html",
"data[merges][EMAIL]": "api+unsub@mailchimp.com",
"data[merges][FNAME]": "Mailchimp",
"data[merges][LNAME]": "API",
"data[merges][INTERESTS]": "Group1,Group2",
"data[ip_opt]": "10.20.10.30",
"data[campaign_id]": "cb398d21d2"

Profile updates

"type": "profile",
"fired_at": "2009-03-26 21:31:21",
"data[id]": "8a25ff1d98",
"data[list_id]": "a6b5da1054",
"data[email]": "api@mailchimp.com",
"data[email_type]": "html",
"data[merges][EMAIL]": "api@mailchimp.com",
"data[merges][FNAME]": "Mailchimp",
"data[merges][LNAME]": "API",
"data[merges][INTERESTS]": "Group1,Group2",
"data[ip_opt]": "10.20.10.30"

Note that you will always receive a profile update at the same time as an email update.

Email address changes

"type": "upemail",
"fired_at": "2009-03-26 22:15:09",
"data[list_id]": "a6b5da1054",
"data[new_id]": "51da8c3259",
"data[new_email]": "api+new@mailchimp.com",
"data[old_email]": "api+old@mailchimp.com"

Cleaned emails

For cleaned emails, the reason will be hard (for hard bounces) or abuse.

"type": "cleaned",
"fired_at": "2009-03-26 22:01:00",
"data[list_id]": "a6b5da1054",
"data[campaign_id]": "4fjk2ma9xd",
"data[reason]": "hard",
"data[email]": "api+cleaned@mailchimp.com"

Campaign sending status

"type": "campaign",
"fired_at": "2009-03-26 21:31:21",
"data[id]": "5aa2102003",
"data[subject]": "Test Campaign Subject",
"data[status]": "sent",
"data[reason]": "",
"data[list_id]": "a6b5da1054"

Webhooks security

Using an SSL-enabled URL, Mailchimp supports HTTP or HTTPS URLs to increase security. To further increase security, consider taking additional steps to ensure that information is coming from Mailchimp.

In addition to keeping the URL private, we suggest that you include a secret key in the webhook URL and check the GET parameter in your scripts.