About Webhooks

Webhooks allow you to collect information about list/audience event changes as they happen in Mailchimp. All you have to do is enter a valid URL, and then select the type of updates you want to receive. The purpose of this guide is to explain how to use webhooks in Mailchimp so you can get updates in near realtime.

For general information about webhooks, go to PBWiki Webhooks.

Configuring a Webhook for a List/Audience

You configure and manage a webhook in one of two ways: directly in your Mailchimp account or through the API 3.0.

  • For instructions on how to configure webhooks in your Mailchimp account, visit the knowledgebase.
  • To learn how to configure webhooks using the API 3.0, refer to the Webhooks reference guide.

Refer to events and event sources below for the list of supported event triggers.

Note

While Mailchimp sends HTTP POST for actual data, the webhook validator only sends HTTP GET requests. You’ll need to allow both so your webhook functions properly.

Securing Webhooks

By using an SSL-enabled URL, Mailchimp supports HTTP or HTTPS URLs to increase security. To increase security even more, you may wish to take additional steps to ensure that information is coming from Mailchimp.

Aside from trying to keep the URL private, we suggest that you include a secret key in the webhook URL and check the GET parameter in your scripts.

Supported Events

You can configure webhooks to trigger when the following events occur:

  • Subscribes
  • Unsubscribes
  • Profile Updates
  • Cleaned address
  • Email changed
  • Campaign sending (Note: Due to the way sending works, this option is currently all or nothing and cannot be limited to where the change originated.)

Note

Batch operations in API 3.0 support webhooks, but the implementation is slightly different. Learn more in Use Batch Operations.

Event Sources

You can configure webhooks to trigger based on the following event source.

  • By a subscriber
  • By an account admin
  • Via the API

Event Data

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 cancelled 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",
"data[reason]": "hard"

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"

Email Address Changes

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

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