What are Webhooks?

Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, select when and where you want that URL to receive data about events on your list, and we'll send it to you as the events take place

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

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

Need help getting a script started? We have some contributions in the downloads section

Configuring Webhooks

Webhooks are configured from your MailChimp account. Here are the basic steps:

  1. Log in to your MailChimp account
  2. Navigate to your Lists
  3. Click View Lists on the list you want to configure
  4. Click the List Tools menu option at the top
  5. Click Webhooks

Configuration is simple: Enter a valid url for us to contact, then select the events and event sources (see below for descriptions) you want to have sent to you.

Securing Webhooks

We currently support either HTTP or HTTPS urls, so you can have security by using an SSL-enabled url. But keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. At this time, aside from trying to keep the URL private, our best suggestion is to simply include a secret key in the URL your provide and check that GET parameter in your scripts.

Supported Events

Our Webhooks implementation allows a wide variety of options for the events you want to capture, based on their sources. We support the following events:

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

Event Sources

You can also select the sources you want to be notified about where changes are arriving from. We support these sources of changes:

  • Users via the list-manage.com forms
  • Admins via our web app
  • API calls

Event Data

When an event occurs that you have turned on, 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. Those time frames may be tweaked as we receive feedback from users.

We'll return various 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: 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.

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

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