Skip to content
HookDeploy

Mailgun webhooks

Last verified against Mailgun's documentation on September 27, 2026.

On this page ↓

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

EventWhat it meansTypical use
acceptedMailgun accepted the message for deliveryTrack sends
deliveredThe recipient’s server accepted the messageConfirm delivery
failedDelivery failed, permanently or temporarilySuppress bad addresses, handle temporary failures
openedThe recipient opened the messageMeasure engagement
clickedThe recipient clicked a tracked linkMeasure engagement
unsubscribedThe recipient unsubscribedSync preferences
complainedThe recipient marked the message as spamSuppress 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

BehaviorDetail
Method and formatPOST with a JSON body
Signature locationIn the body: signature.timestamp, signature.token, and signature.signature
Signing schemeHMAC-SHA256 of timestamp + token (no separator), keyed with your HTTP webhook signing key, as hex
SubaccountsA parent-signature field, signed with the primary account’s key
Success200
Reject without retry406
RetriesAny other response is retried over 8 hours, after 5 minutes, 10 minutes, 15 minutes, 1 hour, 2 hours, and 4 hours
Delivered eventsNever retried
Deduplicationevent-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 timestamp and token concatenated 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 406 from 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 for delivered events, 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

  1. In HookDeploy, create an endpoint (for example, Mailgun events) and copy its URL.
  2. 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.
  3. In Mailgun, open your sending domain’s webhooks and add your HookDeploy URL for each event type you want.
  4. Copy your HTTP webhook signing key.
  5. 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.

Capture Mailgun webhooks free

Start free