Test Mailchimp Webhooks Locally (Receive Mailchimp Webhooks on localhost)

You are building a Mailchimp integration and you need to watch your handler react to a real event. The problem hits immediately: Mailchimp will only POST to a public URL, and your handler is running on localhost:8080. Mailchimp has no way to reach it.

The usual workarounds are slow. Deploying to a staging environment for every code change kills your iteration speed. Copying a sample payload out of the docs into curl gives you a guess at the real request, not the exact headers and body Mailchimp actually sends. What you really want is to test Mailchimp webhooks locally — real events, hitting your local handler, on a URL that does not change every time you restart.

This guide shows how to do exactly that.

Why testing Mailchimp webhooks locally is tricky

A webhook is just an HTTP request that Mailchimp sends to a URL when something changes. Mailchimp lives on the public internet; your dev machine usually does not. It sits behind a router, a corporate firewall, or both, with no public IP and no inbound ports open.

So you need something in the middle: a public endpoint Mailchimp can hit that relays each request down to your laptop without you opening a single firewall port. That is what Webhook Relay does — and unlike a random tunnel URL, the endpoint is stable, so you configure Mailchimp once and never touch it again.

Step 1: Inspect the real payload with Webhook Bin

Before you write any handler code, find out what Mailchimp actually sends. Open the free Webhook Bin — no signup — and you get an instant public URL.

1. Copy the Webhook Bin URL.
2. In Mailchimp, go to Audience → Settings → Webhooks, click Create New Webhook, paste the URL, and choose the events.
3. Trigger a real event and inspect the captured request.

You will see the full body and every header. Mailchimp marketing webhooks are application/x-www-form-urlencoded, not JSON. You get a type (e.g. subscribe) and a data[...] map (email, list id, merge fields). Parse it as form data, not JSON.

Now you know the exact shape of the data before writing a line of code. For more on this approach, see How to test webhooks and What is a webhook.

Step 2: Forward the events to localhost with the relay agent

Once you know the payload, route those same events into your local handler. Sign up for Webhook Relay, install the relay agent (CLI or Docker), and create a bucket — say mailchimp. The bucket gives you a stable public input endpoint.

Start forwarding to your local server:

relay forward --bucket mailchimp http://localhost:8080/webhook

The agent opens an outbound connection to Webhook Relay and streams every incoming request down to http://localhost:8080/webhook. Because the connection is outbound, there are no firewall ports to open and no public IP needed — this works from your laptop, behind a corporate proxy, or inside a Kubernetes cluster. Running in Docker? The same command works in the official webhookrelay/webhookrelayd image. Full details are in the localhost forwarding docs.

Now point the Mailchimp webhook at your Webhook Relay endpoint (or create it there from the start), trigger an event, and watch it arrive on localhost.

Mailchimp-specific configuration and quirks

A few Mailchimp details worth knowing:

• Where to add it: Audience → Settings → Webhooks.
• Form-encoded: the body is application/x-www-form-urlencoded with a type and data[...] map — parse it as form data, not JSON.
• No HMAC: marketing webhooks aren't signed — put a secret in the URL and check it. Mandrill (transactional) signs separately.
• Verify endpoint: Mailchimp first sends a GET to confirm the URL exists, then POSTs events.

Step 3: Verify the Mailchimp webhook signature

Mailchimp's marketing webhooks are not signed with an HMAC, so there's nothing to recompute. Instead, secure the endpoint by putting a secret in the webhook URL query string (for example ?key=long-random-value) and rejecting any request that doesn't carry it. If you use Mandrill (transactional email), that product does sign — it sends an X-Mandrill-Signature (HMAC-SHA1, base64) computed over the webhook URL plus the sorted POST parameters, which you verify with your Mandrill webhook key.

To sanity-check an HMAC implementation, paste a captured body, your secret, and the received signature into the free HMAC signature verifier. For language-specific code and the common pitfalls (reading the body after a JSON parser has already consumed it, timing-safe comparison), read Verify a webhook signature.

Replay and iterate

This is where local development gets fast:

• Replay from Webhook Relay — past requests are stored on your bucket, so you can resend a captured event against your handler without touching Mailchimp at all.
• Iterate on your handler by editing code and replaying the same delivery until it behaves correctly. No commits, no pushes, no deploys just to test a single code path.
• Keep relay forward running while you work — events stream straight to localhost as you trigger them in Mailchimp.

Because the Webhook Relay endpoint is stable, you can stop and restart the agent, reboot your machine, or come back next week — the Mailchimp configuration never needs to change.

Get started

1. Inspect the real payload in the free Webhook Bin — no signup needed.
2. Create a Webhook Relay account, install the agent, and run relay forward --bucket mailchimp http://localhost:8080/webhook.
3. Point your Mailchimp webhook at the stable endpoint, trigger an event, and watch it hit localhost.

You will be testing real Mailchimp events against your local handler in a few minutes — no deploys, no open firewall ports, and a URL you configure exactly once.