Please, before you get too deep into anything, make sure that you've read our Getting Started Guide. Thanks!

What are Webhooks?

Webhooks allow you to collect information about events as they happen in near real-time. All you have to do is provide a URL, select when & where you want that URL to receive data about things happening on your list, and we'll send it over to you as things happen.

For general reading on Webhooks, please check out the PBWiki Webhooks page.

For testing info our Webhooks before you setup a bunch of scripts, the PostBin tool is an excellent utility to help see data come across as various events happen in our system.

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

Configuring Webhooks

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

  1. Log into your MailChimp account
  2. Navigating to your Lists
  3. Click the View Lists button on the list you want to configure
  4. Click the List Tools menu option at the top
  5. Click the Webhooks link
Configuration should be pretty straight forward - enter a valid url for us to contact, then select the events and event sources (see below for descriptions) you'd like to have sent to you.

Securing Webhooks

Currently we will support either HTTP or HTTPS urls, so you can get some semblence of security by using an SSL-enabled url. However, keep in mind that your endpoint is going to be wide-open on the internet and you may not want others to be able to submit random data to your systems. At this time, aside from trying to keep the URL private, the best suggestion we have is for you 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 on which events you want to capture based on the source of those events. The events we support are:

  • Subscribes
  • Unsubscribes
  • Profile Updates
  • Email Address Changes
  • Cleaned Emails

Event Sources

You can also select the sources you want to be notified about changes arriving from. The supported sources of changes are:

  • 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 a HTTP POST request to the URL you've specified. If that URL is not available or takes too long to respond (more than 15 seconds), we'll cancel the request and try again later. Retries are done at increasing intervals over the course of 1 hour and 15 minutes. Those time frames may be tweaked as we start to receive feedback from users.

For each event we'll return various data based on the event. Below is a sample data for each event - you can also easily see this using the PostBin 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.

To be clear: below is sample data to show you 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

  "type": "unsubscribe", 
  "fired_at": "2009-03-26 21:54:52", 
  "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"

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[reason]": "hard",
  "data[email]": "api+cleaned@mailchimp.com"