Catch MailChimp Updates in WordPress Using Webhooks
Do you want to be able to track your WordPress users as they subscribe and unsubscribe from your MailChimp lists?
Of course you do, but your MailChimp plugin is probably no help beyond generating that subscribe form. What you need is MailChimp webhooks.
In this article, I’ll show you how to build a simple plugin to update your WordPress site with all your MailChimp list activity.
What Is A Webhook?
A webhook is simply a url that gets called when a certain event takes place, passing pertinent data about the event.
This provides a simple method for one application to take action based on an event happening in another and is perfect for our scenario of wanting to keep track of subscribes and unsubscribes.
Hooking Up MailChimp And WordPress
In this scenario, when a user is subscribed to, or unsubscribed from a list (an event), MailChimp will post the relevant data to a specified URL on our WordPress site that will use the event data to carry out some relevant processing such as updating a subscribed flag.
MailChimp packages up data about the action as a standard HTTP POST, so it is, to all intents and purposes, akin to a form submission where the form’s action is the webhook URL.
MailChimp also does its best to ensure that the webhook is successful. If it doesn’t receive an HTTP 200 (all ok) return code from the webhook URL then it will re-call the webhook. Not as robust as a full-blown message queue system but decent enough for our needs.
So, to get MailChimp and WordPress talking we need to tell MailChimp the URL of the webhook and when to call it and we need to extend WordPress to handle that call.
As you’ll need information from your WordPress configuration to set up MailChimp, let’s start with setting up WordPress.
Setting Up WordPress
You’ve got two options when it comes to setting up WordPress:
- Use our MailChimp Integration plugin, which has webhook support built-in.
- Use this custom plugin to use in conjunction with your current MailChimp plugin.
Using WPMU DEV’s MailChimp Integration Plugin
Once you’ve installed or updated to the latest version of the MailChimp Integration plugin, head to Settings > MailChimp. Enter your API key, select the list you want to synchronize and configure any of the other options. Then, once you’ve saved your settings, you will see the Webhooks options appear.
There are just two options to set:
- Specify a unique webhook key: This acts as a low-fi security mechanism as the webhook function won’t process any request that doesn’t contain the security key
- Action to take when user unsubscribes from list: Decided whether to delete a user from your WordPress site when they unsubscribe or merely mark as unsubscribed
When you’ve set these two options, click on Save Changes.
Under the webhook key text box, you’ll see a URL listed. Copy this and head over to MailChimp.
Using the Custom Plugin
First thing to do is download and install the plugin. When you have the plugin installed, go to Settings > MailChimp Webhooks.
There’s not much here but it’s fairly important. The options are as follows:
- Create new user on subscribe? If checked, a subscribe event will create a new user in your WordPress site with the role of subscriber, if none currently exists.
- Delete user on unsubscribe? If checked, when a user unsubscribes they will be deleted from the WordPress site.
- Specify a unique webhook key? Like the MailChimp Integration plugin, the webhook function won’t process any request that doesn’t contain the specified security key
- Write activity to log? Checking this option will cause all activity to be written to a log – useful for debugging.
The plugin uses the email address to check for existing users and if users are not being created and deleted then a unique flag is added to the user record so that, as a site owner, you can quickly see if the user is subscribed or not.
Once you have configured the settings and added your webhook key, click on Save Changes.
You’ll also see that the webhook URL listed under the webhook key has changed in line with your webhook key. Copy this URL as you are going to need it for the next step, configuring MailChimp.
Configuring Webhooks In MailChimp
Webhooks in MailChimp are configured on a per-List basis, so jump into your MailChimp account, find the appropriate List, click on Settings > Webhooks, and then on the Add A New Webhook button.
You’ll be presented with a form like this:
This is where you paste the webhook URL list on the WordPress plugin’s settings page.
What type of updates should we send?
Fairly self-explanatory, this a list of events that you can track. There are a number to choose from but keep in mind that, out-of-the-box, the WordPress plugin you’ve installed only actions subscribes and unsubscribes.
Checking all the events doesn’t hurt but if you want to action more events then you’ll need to extend the plugin (see later).
Only send updates when a change was made by:
The right-hand list of checkboxes allows you to select events based on how the event was initiated.
- A subscriber: you’ll definitely want to check a subscriber as this covers all the manual actions, such as clicking on a link in an email.
- Account admin: that’s you and I think this is worth keeping as it means that any changes you make in the MailChimp admin interface, except for imports, will be passed through to your WordPress site.
- Via the API: if, like the majority of WordPress / MailChimp users, you are just using a MailChimp plugin to generate a sign-up form then checking this will ensure that you can track those sign-ups and add the users to your website.
It’s worth reiterating that bulk imports do not fire webhooks, which is understandable (for big lists) but annoying (for smaller lists). One apparent workaround is to bulk import to a temporary list and use the bulk action move to move the subscribers to the intended destination: this will fire the webhook for each new subscriber.
Obviously, you don’t want to do this for a very large list.
When you’ve checked all the appropriate boxes, click on Save and the webhook will be created.
You’ll notice that you can add multiple webhooks for the one list which might be useful if you wanted several sites to track the same List.
Testing Your Webhooks
The easiest way to test your webhook is to manually add a subscriber to the List in MailChimp using the form at Add Subscribers > Add Subscribe.
Complete the form and click on Subscribe and if MailChimp confirms the add was successful go to back to your WordPress admin interface and click on Users.
Look for the user with the email address that you added in MailChimp (if it did not already exist and you have set the WordPress plugin to Create new user on subscriber to true then the user will have been created) and click to Edit. Scroll down to the bottom of the profile page and you’ll see the following:
Now go back to MailChimp, click on Manage Subscribers > View Subscribers and you’ll get a list of current subscribers.
Click in the checkbox next to your test subscriber and two new action buttons appear at the top of the page, Actions and Delete. Either click on Actions > Unsubscribe, or Delete and then Confirm.
Now back into WordPress and if you are not deleting users on unsubscribe the MailChimp Newsletter subscriber checkbox will be empty, otherwise the user will have been deleted.
You’ve now configured MailChimp webhooks and in doing so can now track changes to your subscriber list that take place outside of your WordPress site which in the majority of set-ups will be the norm.
Once you are tracking these (un)subscribe events, you can start to think about how you might be able to leverage this data to encourage newsletter sign-ups. One obvious use is to provide subscriber only content and we’ll be taking a look at how to implement such a social paywall in an upcoming post.
How The Custom Plugin Works
By virtue of the fact you are reading this, you must be (slightly) curious as to how this works on the WordPress side of things. Good on you.
The plugin does the following:
- Sets up the webhook URL,
- Intercepts calls to the webhook URL, works out what the event is and then passes the data to the appropriate handler (subscribe/unsubscribe),
- Adds the MailChimp Newsletter section to the User Profile display, and
- Creates the settings page using the Settings API.
I’m not going to go through the settings page creation as I’ve covered this in previous posts, so let’s start with setting up the webhook URL.
Setting Up The Webhook URL
When the plugin is activated it runs an initialization function. This function hooks into the init action to make use of the add_rewrite_rule and the add_rewrite_tag functions to change a request for <site name>/webhook?key=yourkey to <site name>/index.php?webhook=1&key=yourkey.
Intercepting The Webhook URL
The init function also adds a hook for the parse_request action. In this custom function, there’s a simple check for the existence of webhook in the query_vars (remember we rewrote the URL from /webhook to index.php?webhook=1) and if found the function to handle the webhook is called.
The exit() command ensures that no subsequent processing takes place.
Actioning The Webhook Event
All webhooks requests are initially handled by the one function which:
- Checks to make sure the request contains data ($_POST),
- Checks that the key supplied matches the key you set in the plugin’s settings, and
- Determines the type of event and calls the appropriate handler.
You’ll notice that an activity log is updated (this is written to the plugin’s directory) and that all the events are catered for, although only the subscribe and unsubscribe functions have been fleshed out.
If you want to also take action on a cleaned up email or profile event then you’ll need to expand these functions in the plugin.
Handling A Subscribe Event
The subscribe event contains the following payload in the HTTP POST:
"type": "subscribe", "fired_at": "2009-03-26 21:35:57", "data[id]": "8a25ff1d98", "data[list_id]": "a6b5da1054", "data[email]": "[email protected]", "data[email_type]": "html", "data[merges][EMAIL]": "ap[email protected]", "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"
As you can see there’s quite a bit of information here. You could take a different action depending on the list_id, for example (useful if your site has multiple lists each with its own subscriber benefits) and perhaps even sync up the interests.
To keep things simple, though, the plugin is only interested that this subscriber has been added to a list.
The subscribe function first checks to see if the subscriber email exists. If it doesn’t and new users should be created then it uses the wp_insert_user function to create a new WordPress user with the role of Subscriber from the MailChimp data.
A new user meta variable, _newsletter_subscriber, is added to the user (either newly created or pre-existing) with a value of 1. This appears as the checkbox under MailChimp Newsletter on the user profile.
Handling An Unsubscribe Event
The unsubscribe event data looks something like this:
"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]": "[email protected]", "data[email_type]": "html", "data[merges][EMAIL]": "[email protected]", "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"
Again, plenty of additional information such as reason and campaign that might be useful but, for now, we are concentrating simply on the request to unsubscribe.
Like subscribe, the first action is to check for the existence of a user with a matching email address.
If one is found and we are deleting users on unsubscribe the wp-admin/includes/user.php file is included before calling the wp_delete_user function. Otherwise, the _newsletter_subscriber user meta variable is set to 0.
Displaying Subscriber Status on the User Profile
You’ll have noticed that in the subscribe and unsubscribe functions, the user meta variable _newsletter_subscriber is set to 1 and 0 according to the event.
Displaying this value is a simple matter of hooking into the show_user_profile and edit_user_profile actions to output the appropriate output. As this is read-only (we want to let MailChimp handle the events) the control is disabled.
The plugin writes plenty of detail to a log file, which you’ll find invaluable when testing your own set-up.
An option in the plugin’s settings page allows you to switch logging on and off and there’s also a link to the current log file for easy viewing.
Get Hooked and Stay in Sync
That MailChimp is so popular with WordPress site owners is hardly surprising: its free plan with 12,000 emails per month enables the majority of those owners to use this industrial-strength email app for no cost.
But whilst there’s always been plenty of excellent plugins for getting your visitors to subscribe to your newsletters, aside from MailChimp Integration, the process has been something of a black hole as far as tracking those subscribes and unsubscribes in your WordPress site.
Webhooks shine a bright light into that black hole, meaning you can fairly accurately track who is a current subscriber. Not only does this potentially save a lot of tedious downloading and uploading of subscriber lists it can also open up some interesting promotional opportunities such as subscriber-only content.