Mailchimp Transactional (Mandrill) webhooks
Last verified against Mailchimp Transactional (Mandrill)'s documentation on September 27, 2026.
Mailchimp Transactional, formerly Mandrill, sends webhooks for what happens to the email you send: sends, deferrals, bounces, opens, clicks, spam reports, unsubscribes, and rejections, plus inbound email. Its webhooks have an unusual shape. Events arrive in batches as a form field, and the signature covers the webhook URL, not just the body. That URL detail is what breaks verification behind proxies, and it matters with HookDeploy too. This page covers what Mandrill sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Mandrill sends webhooks for
| Event | Typical use |
|---|---|
send | Track sends |
deferral | Watch delivery delays |
hard_bounce, soft_bounce | Suppress bad addresses |
open, click | Measure engagement |
spam | Suppress complainers |
unsub | Sync unsubscribes |
reject | Catch messages Mandrill refused to send |
Each POST can carry many events in its mandrill_events array. Every event has an event type and a msg object with the message’s details, including its _id, recipient email, state, tags, and any metadata you attached.
How Mandrill delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with application/x-www-form-urlencoded data. The mandrill_events field holds a JSON array |
| Signature header | X-Mandrill-Signature |
| Signing scheme | HMAC-SHA1 over the registered webhook URL followed by each POST field’s key and value, sorted by key, base64-encoded |
| Test request | On creation, a POST with an empty mandrill_events array, signed with the key test-webhook |
| Success | 200 |
| Failures | Batches that don’t get a 200 are queued and retried later |
| Key rotation | A reset key takes effect immediately |
| Message data | Mailchimp Transactional keeps message data for 30 days |
Common Mandrill webhook errors and how to fix them
Signature never matches
- Wrong URL. The signature starts with the URL exactly as registered, including scheme, trailing slash, and query string. Behind a proxy, your app sees a different URL. Read the registered URL from configuration.
- Hex instead of base64. Mandrill base64-encodes the binary HMAC. Comparing against a hex digest always fails.
- Parsed fields. Sign the raw
mandrill_eventsstring as it arrived, not a re-serialized version.
The webhook won’t save
Mandrill checks the URL with a test request when you create the webhook. The test has an empty event array and is signed with test-webhook, not your key. Return 200 for an empty batch.
Events lost during key rotation
Resetting the key takes effect immediately. If your handler accepts batches it can’t verify, or drops them with a 200, those events are gone. Reject unverifiable batches with a non-200, so Mandrill retries them after you deploy the new key.
Only one event processed
Each POST is a batch. Loop over the whole mandrill_events array.
Data older than 30 days is gone
Mailchimp Transactional keeps message data for 30 days. Store the events you need longer.
Why use HookDeploy with Mandrill
Keep events longer than 30 days
HookDeploy keeps every captured batch for your plan’s retention period, from 7 days on Free to 365 days on Enterprise, with the full body and headers.
Capture every batch
HookDeploy captures each batch at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down, batches wait in HookDeploy.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
One webhook, many systems
Send each batch to your app, your CRM, and an analytics pipeline in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems Mandrill can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers batches to a local port, so a private service can receive them without a public endpoint.
Know the limits
- Rejected batches. HookDeploy has already answered Mandrill with a
200, so a non-200from your handler, including during key rotation, becomes a failed forward in HookDeploy, which you retry or replay after deploying the new key. Mandrill doesn’t retry it. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Mandrill queues and retries. Paid plans keep accepting traffic past the included volume.
Signatures through HookDeploy
Mandrill signs the URL you registered, which with HookDeploy is your HookDeploy endpoint URL. HookDeploy forwards the form body and the X-Mandrill-Signature header unchanged, so your handler can verify the signature, as long as it signs with that registered HookDeploy URL, not its own URL.
If you add an endpoint token to the URL as ?token=, it’s part of the registered URL, so include it in the string you sign. HookDeploy removes the token before forwarding, so read the full registered URL from configuration rather than rebuilding it from the request.
A transformation, or a privacy filter that changes the stored copy used for retries and replays, changes the body, and then the signature won’t match at that destination.
Set up Mandrill with HookDeploy
- In HookDeploy, create an endpoint (for example,
Mandrill events) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- In Mailchimp Transactional, open Webhooks and add a webhook. Choose your events, and use your HookDeploy URL as the post-to URL.
- Copy the webhook’s key, and configure your handler with the key and the exact URL you registered.
- Use Send Test, and confirm the batch appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
// The URL exactly as registered in Mailchimp Transactional: your HookDeploy URL, query string included.
const REGISTERED_URL = process.env.MANDRILL_WEBHOOK_URL;
app.post('/webhooks/mandrill', express.urlencoded({ extended: false }), async (req, res) => {
let signed = REGISTERED_URL;
for (const key of Object.keys(req.body).sort()) signed += key + req.body[key];
const expected = crypto
.createHmac('sha1', process.env.MANDRILL_WEBHOOK_KEY)
.update(signed)
.digest('base64'); // base64, not hex
const received = req.get('x-mandrill-signature') ?? '';
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
const events = JSON.parse(req.body.mandrill_events ?? '[]');
if (events.length === 0) return res.sendStatus(200); // test request
if (!valid) return res.status(401).send('Invalid signature');
res.sendStatus(200);
for (const event of events) {
await enqueue({ messageId: event.msg?._id, type: event.event, ts: event.ts, event });
}
// Deduplicate on messageId plus type and ts in your worker.
});
FAQ
How is X-Mandrill-Signature calculated?
Start with the webhook URL exactly as you entered it in Mailchimp Transactional, including any query string. Append each POST field's key and value, sorted by key, with no delimiters. Compute an HMAC-SHA1 with the webhook's key and base64-encode the binary result. A hex signature won't match.
Why does Mandrill signature verification fail behind a proxy?
The signature covers the URL Mandrill posted to. Behind a proxy, a load balancer, or HookDeploy, your app sees a different URL than the one registered. Always sign with the registered URL from configuration, never the incoming request's URL.
Why did my handler receive an empty batch?
When you create a webhook, Mandrill posts a test request with an empty mandrill_events array, signed with the generic key test-webhook rather than your webhook's key. Your handler should return 200 for an empty batch.
Why are Mandrill events form-encoded?
Mandrill posts application/x-www-form-urlencoded data with a single mandrill_events field. That field holds a JSON array of events. Parse the form, then parse mandrill_events as JSON.
What happens if my endpoint rejects a batch?
Mandrill queues a batch that doesn't get a 200 and retries it later. Mailchimp recommends rejecting batches with invalid signatures with a non-200 status, so you don't lose events while rotating the webhook key.
Does HookDeploy break Mandrill signature verification?
Not if you sign with the right URL. Mandrill signs the HookDeploy URL you registered, and HookDeploy forwards the form body and X-Mandrill-Signature unchanged. Your handler must use that registered HookDeploy URL, including its query string, when it computes the signature.