Skip to main content
  • Why Mailchimp?
  • Marketing Platform
    • Illustration of stars and planets Overview

      All the tools you need to market smarter and grow faster.

    • Illustration of a finger tip puppet Audience
      • Marketing CRM
      • Audience Dashboard
      • Tags
      • Segmentation
      • Behavioral Targeting
      • Lookalike Audiences
    • Brand
      • Content Studio
      • Templates
      • Domains
      • Websites Beta
    • Layered squares stacked Campaigns
      • Email
      • Social Media
      • Landing Pages
      • Digital Ads
      • Postcards
      • Automations
    • Illustration of a magnifying glass Insights
      • Reports & Analytics
      • Smart Recommendations
      • Integrations
  • Pricing
  • Resources
    • Overview
    • Mailchimp 101

      Everything you need to get started

    • Marketing Tips

      Learn how to master marketing

    • Guides & Tutorials

      Get step-by-step help with Mailchimp

    • MCP - Illustration Mailchimp Presents

      Entertainment made for entrepreneurs

  • Log In
  • Sign Up Free
    • Audience
    • Dashboard
    • Campaigns
    • Reports
    • Account
In this article
  • Create a webhook in your Mailchimp account
  • Create a webhook using the API
  • How it works
  • Webhooks security
  • Developer
  • Developer Guides

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.

  1. Log into Mailchimp, and then navigate to the Audience page.
  2. Select the drop-down menu next to the audience you want to work with, and then choose Settings.
  3. On the Settings page, click Webhooks.
  4. Click Create New Webhook.
  5. 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
  6. Select the boxes next to each update type to choose the events that will trigger your webhook.
  7. 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.

Mailchimp Presents

A Kyrgyz man attempts to transform his village into a tourism destination.

A collection of short-form series, films, and podcasts created with entrepreneurs in mind. Now playing: My Dear Kyrgyzstan, an inspiring new documentary from Mailchimp.

Learn more

Company

  • Our Story
  • Careers
  • Contact
  • Newsroom

Product

  • Email
  • Mobile App
  • Help
  • Developers
  • Status
  • Security
  • What's New

Community

  • Partner Program
  • Experts Directory
  • Integrations Directory
  • Agencies
  • Events
  • Marketing Glossary
  • Facebook
  • Twitter
  • Instagram
  • LinkedIn
  • YouTube
  • [KB]
  • Get it on Google Play

©2001-2019 All Rights Reserved. Mailchimp® is a registered trademark of The Rocket Science Group. Apple and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries. Mac App Store is a service mark of Apple Inc. Google Play and the Google Play logo are trademarks of Google Inc. Privacy & Terms