Mailgun webhooks
Last verified against Mailgun's documentation on September 27, 2026.
Mailgun sends webhooks for what happens to the email you send: accepted, delivered, failed, opened, clicked, unsubscribed, and complained. Its delivery rules have two surprises. Delivered events are never retried, so one bad moment on your server loses delivery confirmations for good. And a 406 response tells Mailgun to stop retrying, while every other non-200 response keeps it trying for 8 hours. This page covers what Mailgun sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Mailgun sends webhooks for
| Event | What it means | Typical use |
|---|---|---|
accepted | Mailgun accepted the message for delivery | Track sends |
delivered | The recipient’s server accepted the message | Confirm delivery |
failed | Delivery failed, permanently or temporarily | Suppress bad addresses, handle temporary failures |
opened | The recipient opened the message | Measure engagement |
clicked | The recipient clicked a tracked link | Measure engagement |
unsubscribed | The recipient unsubscribed | Sync preferences |
complained | The recipient marked the message as spam | Suppress immediately |
Webhooks are configured per domain. Each POST has a JSON body with a signature object and an event-data object, which includes the event type, a timestamp, and a unique id.
Inbound email handled by Mailgun Routes is posted separately, as form data.
How Mailgun delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with a JSON body |
| Signature location | In the body: signature.timestamp, signature.token, and signature.signature |
| Signing scheme | HMAC-SHA256 of timestamp + token (no separator), keyed with your HTTP webhook signing key, as hex |
| Subaccounts | A parent-signature field, signed with the primary account’s key |
| Success | 200 |
| Reject without retry | 406 |
| Retries | Any other response is retried over 8 hours, after 5 minutes, 10 minutes, 15 minutes, 1 hour, 2 hours, and 4 hours |
| Delivered events | Never retried |
| Deduplication | event-data.id |
Common Mailgun webhook errors and how to fix them
Signature never matches
- Wrong key. Webhooks are signed with the HTTP webhook signing key, not your API key.
- Wrong input. The HMAC covers
timestampandtokenconcatenated with no separator. The body itself isn’t part of the signature. - Wrong encoding. The signature is lowercase hex.
Rejected requests keep coming back
Mailgun only stops on 200 or 406. If your handler answers a bad signature with 400 or 401, Mailgun retries it for 8 hours. Return 406 for requests you want Mailgun to give up on.
Delivery confirmations missing
Mailgun doesn’t retry delivered events. If your server is down, slow, or returns an error when one arrives, that confirmation is gone. Fetch missed events from Mailgun’s Events API to backfill.
Retries rejected as replay attacks
Mailgun suggests caching tokens to block replayed requests. But Mailgun’s own retries resend the same signature block, so a strict token cache rejects legitimate retries. Deduplicate on event-data.id instead.
Events for subaccounts fail verification
Events for a subaccount’s domain are signed with that subaccount’s key. Verify parent-signature with the primary account’s key instead, so one receiver works for every subaccount.
Why use HookDeploy with Mailgun
Never lose a delivered event
Mailgun’s delivered events get one attempt. HookDeploy captures every webhook at Cloudflare’s edge and responds with a 200 right away, before forwarding it to your server. If your server is down, the event is still 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.
- History. HookDeploy keeps captured events for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
Signatures survive retries and replays
Mailgun’s signature is in the body, and HookDeploy forwards the body unchanged, so retries and replays verify exactly like the original delivery.
One webhook, many systems
Send each event 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 Mailgun can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a private service can receive Mailgun events without a public endpoint.
Know the limits
- Your handler’s 406 stays with HookDeploy. HookDeploy has already answered Mailgun. A
406from your handler is a failed forward in HookDeploy, not a signal to Mailgun. - Transformations and privacy filters. Either one changes the body, and then the signature won’t match at that destination.
- Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Mailgun retries, except fordeliveredevents, which are lost. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
Mailgun’s retries, HookDeploy’s retries, and replays all carry the original signature block, with the original timestamp and token.
- Don’t reject repeated tokens from requests that come through HookDeploy, or legitimate retries and replays fail. Check an auth header you inject on the destination to recognize them.
- Be careful with timestamp age checks. A replay can be days old. Apply an age limit only to requests that don’t carry your injected header.
- Deduplicate on
event-data.id.
Set up Mailgun with HookDeploy
- In HookDeploy, create an endpoint (for example,
Mailgun events) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery. Add a header
Authorization: Bearer YOUR_HANDLER_SECRET, and set the destination’s retries. - In Mailgun, open your sending domain’s webhooks and add your HookDeploy URL for each event type you want.
- Copy your HTTP webhook signing key.
- Send a test webhook from Mailgun, and confirm it 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();
app.post('/webhooks/mailgun', express.json(), async (req, res) => {
const { timestamp, token, signature } = req.body.signature ?? {};
const expected = crypto
.createHmac('sha256', process.env.MAILGUN_WEBHOOK_SIGNING_KEY)
.update(`${timestamp}${token}`) // no separator
.digest('hex');
const valid =
typeof signature === 'string' &&
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!valid) return res.status(406).send('Invalid signature'); // 406: don't retry
res.sendStatus(200);
const event = req.body['event-data'];
await enqueue({ eventId: event.id, type: event.event, recipient: event.recipient, event });
// Deduplicate on eventId (event-data.id) in your worker.
});
FAQ
How do I verify a Mailgun webhook?
The signature is in the JSON body, not a header. Concatenate signature.timestamp and signature.token with no separator, compute an HMAC-SHA256 with your HTTP webhook signing key, and compare the hex result to signature.signature. The signing key is separate from your API key.
Does Mailgun retry failed webhooks?
For most events, yes. Unless your endpoint returns 200 or 406, Mailgun retries over 8 hours, after 5 minutes, 10 minutes, 15 minutes, 1 hour, 2 hours, and 4 hours. Delivered events are the exception and are never retried.
What does returning 406 to Mailgun do?
A 406 Not Acceptable tells Mailgun the POST is rejected, and it won't retry it. Use it for events you intentionally don't process. Any other non-200 response is retried.
Why do my retried Mailgun webhooks fail verification?
If your handler caches each token to block replayed requests, a legitimate retry or replay reuses the same token and gets rejected. Mailgun's retries resend the original signature block. Deduplicate on the event ID instead, and only use token caching for requests that don't come through a trusted path.
Does HookDeploy break Mailgun signature verification?
No. The signature lives in the body, and HookDeploy forwards the body unchanged, so first deliveries, retries, and replays all verify. A transformation or privacy filter changes the body, and then the signature won't match at that destination.
What are parent signatures?
For domains that belong to a subaccount, Mailgun adds a parent-signature field computed with the primary account's key, so one receiver can verify events for every subaccount without knowing each subaccount's key.