What are Webhooks?

Webhooks allow you to collect information about events as they happen in near real-time. Once you provide a URL and select the type of information that you want to receive, we’ll send that data to you as the events take place.

For general reading on Webhooks, read the PBWiki Webhooks page.

Configuring Webhooks

Webhooks can be created and managed through API 3.0 or in your MailChimp account. To create a webhook in MailChimp:

  1. Log in to your MailChimp account
  2. Navigate to your Lists
  3. Choose the list that you wish to configure
  4. Click the Settings menu option, then choose Webhooks
  5. Click Create New Webhook

To configure a webhook, provide a valid URL for us to contact, then select the events and event sources you want to have sent to you.

Note

While we do send HTTP POST for actual data, our webhook validator will only send HTTP GET requests. You’ll need to allow both in order for your webhook to function properly.

Securing Webhooks

We currently support either HTTP or HTTPS URLs, so you can increase security by using an SSL-enabled URL. To further increase security, you may wish to take additional steps to ensure that information is coming from MailChimp.

At this time, aside from trying to keep the URL private, our suggestion is to include a secret key in the URL that you provide and check that GET parameter in your scripts.

Supported Events

Our Webhooks implementation allows you to choose the events that will trigger a webhook, meaning that you receive only the information that you want. We support the following events:

  • Subscribes
  • Unsubscribes
  • Profile Updates
  • Email Address Changes
  • Cleaned Emails
  • Campaign Sending status (these events can not be limited by source)

Note

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

Event Sources

You can also configure webhooks to trigger based on the event’s source. We support the following event sources:

  • By a subscriber
  • By a MailChimp account user
  • Via the API

Event Data

When a webhook triggers based on your configured settings, we’ll send an HTTP POST request to the URL you’ve specified. If that URL is unavailable or takes too long to respond (more than 15 seconds), we’ll cancel the request and try again later. Retries happen at increasing intervals over the course of one hour and 15 minutes.

We’ll return different data based on each event. Below is sample data for each event. You can also see this using the RequestBin tool mentioned above. Generally speaking, you’ll see each event has a type and a fired_at field to help you track the type of event and get a timestamp (in GMT) for the event.

This is sample data to show you the fields returned - the POST request actually sends key/value pairs, just like a normal HTML Form Submission

Note

To test our Webhooks before setting up scripts, a tool like RequestBin can be an excellent utility that helps you see data come across as various events happen in our system.

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” will either be “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

Reason will be one of “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"