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.

9 events covered

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

Signature field
signature.signature
Scheme
HMAC-SHA256, hex
Signed material
{timestamp}{token}

signature.timestamp followed by signature.token, with no separator. event-data isn't signed.

How events are identified
event-data.event field in the body
Body format
JSON

Content type: application/json.

Envelope
signature, event-data
Agent skill
npx skills add hookdeck/webhook-skills --skill mailgun-webhooks

Verify Mailgun webhooks →

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.
  • Mailgun's docs describe no way to resend a webhook yourself, so log what you receive.

Delivery behaviour

  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 →
  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 →
  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 →
  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 →

Mailgun webhook best practices

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

accepted · delivered · failed · permanent_fail +1

5 5
engagement

opened · clicked · unsubscribed · complained

4 4

All 9 events →

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.

Not affiliated with Mailgun. Facts are compiled from public sources and linked inline.