Receive and verify Mailgun webhooks. Use when setting up Mailgun webhook handlers, debugging Mailgun signature verification, or handling email events like delivered, failed, opened, clicked, unsubscribed, and complained.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Receive and verify Mailgun webhooks. Use when setting up Mailgun webhook handlers, debugging Mailgun signature verification, or handling email events like delivered, failed, opened, clicked, unsubscribed, and complained.
# HTTP Webhook Signing Key from Mailgun dashboard# (Sending → API Keys → HTTP webhook signing key)
MAILGUN_WEBHOOK_SIGNING_KEY=your-signing-key-here
The signing key is the same for account-level and domain-level webhooks — both use the HTTP Webhook Signing Key from your Mailgun account.
Account-Level vs Domain-Level Webhooks
Mailgun lets you configure webhooks two ways:
Account-level — webhook fires for events across all sending domains on the account. Configure under Sending → Webhooks at the account level.
Domain-level — webhook fires only for events on a specific sending domain. Configure under Sending → Webhooks → [domain].
Both use the same signature scheme and the same Webhook Signing Key. Pick whichever fits your routing — the handler code is identical.
Subaccount parent-signature
If you use Mailgun subaccounts, payloads from a subaccount may include an extra parent-signature field alongside signature. The parent-signature is signed with the parent account's signing key. If you receive subaccount webhooks at a parent-account endpoint, verify parent-signature using the parent's signing key.
Replay Protection
The token field is a one-time 50-character random string. Cache seen tokens (e.g., in Redis with a TTL) and reject duplicates to drop replays:
if (await redis.exists(`mg:${signature.token}`)) {
return res.status(200).send('Duplicate'); // 200 so Mailgun stops retrying
}
await redis.setex(`mg:${signature.token}`, 86400, '1'); // 24h TTL
Optionally reject very stale timestamps (e.g., > 1 hour old), but stay lenient — Mailgun retries can lag.
