Mailgun webhooks
Mailgun webhooks are HTTP POSTs Mailgun sends to your URL when something happens to email you send, such as a delivery, a failure, an open, a click, an unsubscribe or a spam complaint.
These pages cover event webhooks, which report on email you send. Inbound Routes, which post email you receive through forward() and store() actions, have no event types and are covered in the Production guide.
How Mailgun webhooks work
Webhooks save you polling the Logs API for what happened to your mail. Mailgun sends a POST with a JSON body when an event occurs, to URLs you set for each event type, at domain level or account level. Each event type can have up to 3 URLs.
Each body has two keys: signature, which holds the values you verify, and event-data, which holds the event. Read the type from event-data.event, because Mailgun's Webhook Payloads page shows only the inner object. Failures arrive as failed with severity set to permanent or temporary, although you subscribe to them as permanent_fail and temporary_fail. Mailgun's docs name no version header or field, and say events only gain fields.
Key facts
{timestamp}{token} signature.timestamp followed by signature.token, with no separator. event-data isn't signed.
Setting up Mailgun webhooks
- Use the Control Panel or the API:
POST /v3/domains/{domain}/webhooksfor one event type on a domain,POST /v4/domains/{domain}/webhooksfor several, orPOST /v1/webhooksfor your whole account, including subaccounts. Account-level changes can take up to 10 minutes to apply. - US and EU regions are isolated, so create webhooks in each region you send from.
- Mailgun recommends
bin.mailgun.netfor temporary test URLs. To reach your own machine, use a tunnel such as the Hookdeck CLI. - Mailgun's docs describe no way to resend a webhook yourself, so log what you receive.
Delivery behaviour
not documented Mailgun publishes no limit, so return a 200 quickly Retries about 8 hours at 5, 10 and 15 minutes, then 1, 2 and 4 hours, after any code but 200 or 406. The delivery notification isn't retried After retries no resend Mailgun stops, and its docs describe no way to resend, so reconcile from the Logs API Duplicates on retries deduplicate on event-data.id Known failure modes
From Hookdeck's Mailgun guide →-
Missed delivered events
Mailgun doesn't retry the delivery notification, so a
Retries and lost events →deliveredevent sent during an outage never comes back. Reconcile against the Logs API afterwards. -
Retries after a success
Mailgun treats only a 200 as success, so a 201 or 204 brings the event back on its retry schedule. Return 200, or 406 if you never want that POST again.
Timeouts and status codes → -
Events read from the wrong field
Deliveries wrap the event in
Choosing events →event-data, which Mailgun's Webhook Payloads page doesn't show. Readevent-data.event, matchfailedrather thanpermanent_fail, and checkevent-data.severity. -
Duplicate events
A retry can repeat an event you already processed. Deduplicate on
Handle duplicates →event-data.id, which Mailgun says is unique within a day.
Mailgun webhook best practices
- Verify `signature` on every POST.
Recompute the HMAC from
signature.timestampandsignature.tokenwith your Webhook Signing Key. It doesn't coverevent-data, so cache eachtokenand refuse repeats. - Return a 200 fast and queue the work. Mailgun publishes no timeout, and it retries any code other than 200 or 406, including other 2xx codes.
- Deduplicate on `event-data.id`. A retry can repeat an event you already handled. Mailgun says the ID is unique within a day, so expire your keys after about a day.
- Accept events in any order.
Mailgun's docs promise no order. Compare
timestampand rank your states, because a temporaryfailedcan come beforedelivered. - Subscribe only to what you process.
Each event type is configured on its own.
opened,clickedandunsubscribedalso need their tracking turned on. - Reconcile from the Logs API.
deliveredis never retried and other events stop after about 8 hours. Mailgun retains event data for 30 days, though access varies by plan.
Common Mailgun webhook events
Delivery
delivered | Recipient's mail server accepts the message |
permanent_fail | Permanent delivery failure, sent as failed with severity permanent |
temporary_fail | Temporary delivery failure, sent as failed with severity temporary |
Engagement
opened | Recipient opens the message, with open tracking on |
clicked | Recipient clicks a tracked link |
List health
unsubscribed | Recipient clicks the unsubscribe link, with unsubscribe tracking on |
complained | Recipient reports the message as spam through a feedback loop |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
delivery | 5 | 5 |
engagement | 4 | 4 |
In this hub
| Webhook events → | Every covered Mailgun event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Mailgun events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill mailgun-webhooks |
Don't lose delivered events to an outage.
Mailgun never retries its delivery notification. Hookdeck Event Gateway accepts every Mailgun POST, verifies its signature, queues it and retries to your service on your schedule, with a log you can replay from.