# 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](/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#inbound-routes).

Agent skill: `npx skills add hookdeck/webhook-skills --skill mailgun-webhooks` ([details](https://hookdeck.com/webhooks/mailgun/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Mailgun's official docs](https://documentation.mailgun.com/docs/mailgun/user-manual/events/event-structure.md).

[Overview](https://hookdeck.com/webhooks/mailgun) · [Webhook events (9)](https://hookdeck.com/webhooks/mailgun/events) · [MCP events](https://hookdeck.com/webhooks/mailgun/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/mailgun/verify) · [Production guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/mailgun/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature field | `signature.signature` | [Mailgun docs](https://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/securing-webhooks.md) |
| Scheme | `HMAC-SHA256, hex` | [Mailgun docs](https://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/securing-webhooks.md) |
| Signed material | `{timestamp}{token}` signature.timestamp followed by signature.token, with no separator. event-data isn't signed. | [Mailgun docs](https://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/securing-webhooks.md) |
| How events are identified | `event-data.event field in the body` | [Mailgun docs](https://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/securing-webhooks.md) |
| Body format | `JSON` Content type: application/json. | [Mailgun docs](https://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/webhook-payloads.md) |
| Envelope | `signature, event-data` | [Mailgun docs](https://documentation.mailgun.com/docs/mailgun/user-manual/events/event-structure.md) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill mailgun-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/mailgun/skill) |

[Verify Mailgun webhooks](https://hookdeck.com/webhooks/mailgun/verify)

## 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.

## Setting up Mailgun webhooks

- Use the Control Panel or the API: `POST /v3/domains/{domain}/webhooks` for one event type on a domain, `POST /v4/domains/{domain}/webhooks` for several, or `POST /v1/webhooks` for 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.net` for temporary test URLs. To reach your own machine, use a tunnel such as the [Hookdeck CLI](/docs/cli).
- Mailgun's docs describe no way to resend a webhook yourself, so log what you receive.

## Delivery behaviour

- **Timeout:** not documented. Mailgun publishes no limit, so return a 200 quickly. [Guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#timeouts)
- **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. [Guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries:** no resend. Mailgun stops, and its docs describe no way to resend, so reconcile from the Logs API. [Guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#retries)
- **Duplicates:** on retries. deduplicate on `event-data.id`. [Guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#duplicates)

## Known failure modes

1. **Missed delivered events.** Mailgun doesn't retry the delivery notification, so a `delivered` event sent during an outage never comes back. Reconcile against the Logs API afterwards. [Retries and lost events](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#retries)
2. **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](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#timeouts)
3. **Events read from the wrong field.** Deliveries wrap the event in `event-data`, which Mailgun's Webhook Payloads page doesn't show. Read `event-data.event`, match `failed` rather than `permanent_fail`, and check `event-data.severity`. [Choosing events](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#choosing-events)
4. **Duplicate events.** A retry can repeat an event you already processed. Deduplicate on `event-data.id`, which Mailgun says is unique within a day. [Handle duplicates](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#duplicates)

From [Hookdeck's Mailgun guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts).

## Mailgun webhook best practices

- **[Verify `signature` on every POST](https://hookdeck.com/webhooks/mailgun/verify).** Recompute the HMAC from `signature.timestamp` and `signature.token` with your Webhook Signing Key. It doesn't cover `event-data`, so cache each `token` and refuse repeats.
- **[Return a 200 fast and queue the work](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#timeouts).** Mailgun publishes no timeout, and it retries any code other than 200 or 406, including other 2xx codes.
- **[Deduplicate on `event-data.id`](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#ordering).** Mailgun's docs promise no order. Compare `timestamp` and rank your states, because a temporary `failed` can come before `delivered`.
- **[Subscribe only to what you process](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#choosing-events).** Each event type is configured on its own. `opened`, `clicked` and `unsubscribed` also need their tracking turned on.
- **[Reconcile from the Logs API](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts#retries).** `delivered` is 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](https://hookdeck.com/webhooks/mailgun/events#delivered): Recipient's mail server accepts the message
- [permanent_fail](https://hookdeck.com/webhooks/mailgun/events#permanent_fail): Permanent delivery failure, sent as failed with severity permanent
- [temporary_fail](https://hookdeck.com/webhooks/mailgun/events#temporary_fail): Temporary delivery failure, sent as failed with severity temporary

### Engagement

- [opened](https://hookdeck.com/webhooks/mailgun/events#opened): Recipient opens the message, with open tracking on
- [clicked](https://hookdeck.com/webhooks/mailgun/events#clicked): Recipient clicks a tracked link

### List health

- [unsubscribed](https://hookdeck.com/webhooks/mailgun/events#unsubscribed): Recipient clicks the unsubscribe link, with unsubscribe tracking on
- [complained](https://hookdeck.com/webhooks/mailgun/events#complained): Recipient reports the message as spam through a feedback loop

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [delivery](https://hookdeck.com/webhooks/mailgun/events#resource-delivery) | 5 | 5 |
| [engagement](https://hookdeck.com/webhooks/mailgun/events#resource-engagement) | 4 | 4 |

[All 9 events](https://hookdeck.com/webhooks/mailgun/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/mailgun/events): Every covered Mailgun event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/mailgun/mcp-events): How an agent subscribes to Mailgun events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/mailgun/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/mailgun/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/mailgun/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill mailgun-webhooks`
---

Not affiliated with Mailgun. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/mailgun.json) · [Report a correction](https://hookdeck.com/contact)
