Verify Mailgun webhooks

Mailgun signs every event webhook so you can confirm it came from Mailgun. There's no signature header: signature.signature in the JSON body is a hex HMAC-SHA256 of signature.timestamp followed by signature.token, with no separator, keyed with your account's Webhook Signing Key. The body isn't signed, so you can verify after parsing, but a valid signature doesn't show event-data is unchanged. Mailgun's Go SDK has a helper, VerifyWebhookSignature.

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.

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

What to build
Recompute the HMAC over signature.timestamp + signature.token, not the body, and compare
Key
shared secret

Mailgun webhook secret

One Webhook Signing Key covers the whole account. It isn't your API key or a domain sending key. Keep it in an environment variable, not in source code.

  • In the Control Panel: go to Settings, then API Security, then HTTP webhook signing key.
  • Account-wide: a single key covers every domain, plus both event webhooks and Inbound Routes posts.
  • Subaccounts: a delivery for a subaccount's domain also carries signature.parent-signature, computed the same way with the primary account's key, so you can verify with that one key.
  • Rotation: you can rotate the key on the same page. The docs don't say whether the old key keeps working for a time.
  • The docs describe no test and live split.

Source: Mailgun docs ↗

Code

express/src/index.js
javascript
// Generated with: mailgun-webhooks skill
// https://github.com/hookdeck/webhook-skills
require('dotenv').config();
const express = require('express');
const crypto = require('crypto');

const app = express();
const port = process.env.PORT || 3000;

/**
 * Verify a Mailgun signature object.
 *
 * Mailgun puts the signature in the request BODY (not a header) as:
 *   { timestamp, token, signature }
 *
 * The signature is hex(HMAC-SHA256(signingKey, timestamp + token)).
 * For subaccount events a `parent-signature` field may also be present;
 * verify it with the parent account's signing key.
 */
function verifyMailgun(signature, signingKey) {
  if (!signature || !signingKey) return false;

  const { timestamp, token, signature: providedSig } = signature;
  if (!timestamp || !token || !providedSig) return false;

  const expected = crypto
    .createHmac('sha256', signingKey)
    .update(timestamp + token)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(providedSig, 'hex')
    );
  } catch {
    return false;
  }
}

// Health check
app.get('/health', (req, res) => res.json({ status: 'ok' }));

// Mailgun webhook endpoint
// Standard JSON parsing is fine — the signature only covers timestamp+token,
// not the request body, so we don't need raw bytes here.
app.post('/webhooks/mailgun', express.json(), (req, res) => {
  const signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY;
  if (!signingKey) {
    console.error('MAILGUN_WEBHOOK_SIGNING_KEY not configured');
    return res.status(500).json({ error: 'Webhook verification not configured' });
  }

  const signature = req.body && req.body.signature;
  if (!signature) {
    return res.status(400).json({ error: 'Missing signature in request body' });
  }

  if (!verifyMailgun(signature, signingKey)) {
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Optional: subaccount parent-signature verification
  const parentKey = process.env.MAILGUN_PARENT_WEBHOOK_SIGNING_KEY;
  if (signature['parent-signature'] && parentKey) {
    const parentExpected = crypto
      .createHmac('sha256', parentKey)
      .update(signature.timestamp + signature.token)
      .digest('hex');
    const parentSig = signature['parent-signature'];
    let parentOk = false;
    try {
      parentOk = crypto.timingSafeEqual(
        Buffer.from(parentExpected, 'hex'),
        Buffer.from(parentSig, 'hex')
      );
    } catch {
      parentOk = false;
    }
    if (!parentOk) {
      return res.status(400).json({ error: 'Invalid parent-signature' });
    }
  }

  const eventData = req.body['event-data'];
  if (!eventData || !eventData.event) {
    return res.status(400).json({ error: 'Missing event-data' });
  }

  // Dispatch on event type
  switch (eventData.event) {
    case 'accepted':
      console.log(`Accepted: ${eventData.recipient}`);
      break;

    case 'rejected':
      console.log(`Rejected: ${eventData.recipient} - ${eventData.reject && eventData.reject.reason}`);
      break;

    case 'delivered':
      console.log(`Delivered: ${eventData.recipient}`);
      // Your code: mark message as delivered in your database
      break;

    case 'failed':
      // severity is 'permanent' (hard bounce) or 'temporary' (soft bounce)
      console.log(`Failed (${eventData.severity}): ${eventData.recipient}`);
      if (eventData.severity === 'permanent') {
        // Your code: add address to your local suppression list
      }
      break;

    case 'opened':
      console.log(`Opened: ${eventData.recipient}`);
      // Your code: record engagement
      break;

    case 'clicked':
      console.log(`Clicked: ${eventData.recipient} -> ${eventData.url}`);
      // Your code: record click analytics
      break;

    case 'unsubscribed':
      console.log(`Unsubscribed: ${eventData.recipient}`);
      // Your code: remove from mailing list
      break;

    case 'complained':
      console.log(`Complained (spam): ${eventData.recipient}`);
      // Your code: add to suppression list
      break;

    case 'stored':
      console.log(`Stored inbound message at ${eventData.storage && eventData.storage.url}`);
      break;

    case 'list_member_uploaded':
      console.log(`List member uploaded: ${eventData.member && eventData.member.address}`);
      break;

    default:
      console.log(`Unhandled event type: ${eventData.event}`);
  }

  res.json({ received: true });
});

module.exports = app;

if (require.main === module) {
  app.listen(port, () => {
    console.log(`Mailgun webhook server listening on port ${port}`);
    console.log(`Webhook endpoint: http://localhost:${port}/webhooks/mailgun`);
  });
}
nextjs/app/webhooks/mailgun/route.ts
typescript
// Generated with: mailgun-webhooks skill
// https://github.com/hookdeck/webhook-skills
import { NextRequest, NextResponse } from 'next/server';
import { createHmac, timingSafeEqual } from 'crypto';

interface MailgunSignature {
  timestamp: string;
  token: string;
  signature: string;
  'parent-signature'?: string;
}

interface MailgunEventData {
  event: string;
  recipient?: string;
  severity?: 'permanent' | 'temporary';
  url?: string;
  reject?: { reason?: string; description?: string };
  storage?: { url?: string; key?: string };
  [key: string]: unknown;
}

interface MailgunPayload {
  signature: MailgunSignature;
  'event-data': MailgunEventData;
}

/**
 * Verify a Mailgun signature object.
 * The signed content is `timestamp + token` (no separator), hashed with HMAC-SHA256.
 */
function verifyMailgun(signature: MailgunSignature, signingKey: string): boolean {
  if (!signature) return false;

  const { timestamp, token, signature: providedSig } = signature;
  if (!timestamp || !token || !providedSig) return false;

  const expected = createHmac('sha256', signingKey)
    .update(timestamp + token)
    .digest('hex');

  try {
    return timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(providedSig, 'hex')
    );
  } catch {
    return false;
  }
}

function verifyParentSignature(
  signature: MailgunSignature,
  parentSigningKey: string
): boolean {
  const parentSig = signature['parent-signature'];
  if (!parentSig) return true;  // not a subaccount event — nothing to verify

  const expected = createHmac('sha256', parentSigningKey)
    .update(signature.timestamp + signature.token)
    .digest('hex');

  try {
    return timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(parentSig, 'hex')
    );
  } catch {
    return false;
  }
}

export async function POST(request: NextRequest) {
  const signingKey = process.env.MAILGUN_WEBHOOK_SIGNING_KEY;
  if (!signingKey) {
    console.error('MAILGUN_WEBHOOK_SIGNING_KEY not configured');
    return NextResponse.json(
      { error: 'Webhook verification not configured' },
      { status: 500 }
    );
  }

  let payload: MailgunPayload;
  try {
    payload = (await request.json()) as MailgunPayload;
  } catch {
    return NextResponse.json({ error: 'Invalid JSON payload' }, { status: 400 });
  }

  const signature = payload?.signature;
  if (!signature) {
    return NextResponse.json(
      { error: 'Missing signature in request body' },
      { status: 400 }
    );
  }

  if (!verifyMailgun(signature, signingKey)) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  // Optional subaccount parent-signature verification
  const parentKey = process.env.MAILGUN_PARENT_WEBHOOK_SIGNING_KEY;
  if (signature['parent-signature'] && parentKey) {
    if (!verifyParentSignature(signature, parentKey)) {
      return NextResponse.json({ error: 'Invalid parent-signature' }, { status: 400 });
    }
  }

  const eventData = payload['event-data'];
  if (!eventData || !eventData.event) {
    return NextResponse.json({ error: 'Missing event-data' }, { status: 400 });
  }

  switch (eventData.event) {
    case 'accepted':
      console.log(`Accepted: ${eventData.recipient}`);
      break;

    case 'rejected':
      console.log(`Rejected: ${eventData.recipient} - ${eventData.reject?.reason}`);
      break;

    case 'delivered':
      console.log(`Delivered: ${eventData.recipient}`);
      // Mark message as delivered in your database
      break;

    case 'failed':
      // severity is 'permanent' (hard bounce) or 'temporary' (soft bounce)
      console.log(`Failed (${eventData.severity}): ${eventData.recipient}`);
      if (eventData.severity === 'permanent') {
        // Add address to your local suppression list
      }
      break;

    case 'opened':
      console.log(`Opened: ${eventData.recipient}`);
      break;

    case 'clicked':
      console.log(`Clicked: ${eventData.recipient} -> ${eventData.url}`);
      break;

    case 'unsubscribed':
      console.log(`Unsubscribed: ${eventData.recipient}`);
      break;

    case 'complained':
      console.log(`Complained (spam): ${eventData.recipient}`);
      break;

    case 'stored':
      console.log(`Stored inbound message at ${eventData.storage?.url}`);
      break;

    case 'list_member_uploaded':
      console.log('List member uploaded');
      break;

    default:
      console.log(`Unhandled event type: ${eventData.event}`);
  }

  return NextResponse.json({ received: true }, { status: 200 });
}

export async function GET() {
  return NextResponse.json({ status: 'ok', endpoint: '/webhooks/mailgun' });
}
fastapi/main.py
python
# Generated with: mailgun-webhooks skill
# https://github.com/hookdeck/webhook-skills
import hashlib
import hmac
import json
import os
from typing import Any, Dict, Optional

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse

try:
    from dotenv import load_dotenv

    load_dotenv()
except ImportError:
    # dotenv is optional in production
    pass

app = FastAPI(title="Mailgun Webhook Handler")


def verify_mailgun(signature: Dict[str, Any], signing_key: str) -> bool:
    """Verify a Mailgun `signature` object.

    The signed content is the raw concatenation `timestamp + token` (no
    separator), hashed with HMAC-SHA256 and hex-encoded. Compare with the
    `signature` field using a timing-safe comparison.
    """
    if not signature or not signing_key:
        return False

    timestamp = signature.get("timestamp")
    token = signature.get("token")
    provided = signature.get("signature")

    if not (timestamp and token and provided):
        return False

    expected = hmac.new(
        signing_key.encode(),
        (str(timestamp) + str(token)).encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, provided)


def verify_parent_signature(
    signature: Dict[str, Any], parent_signing_key: str
) -> bool:
    """Verify the optional `parent-signature` field for subaccount webhooks.

    Returns True when no parent-signature is present (nothing to verify).
    """
    parent_sig = signature.get("parent-signature")
    if not parent_sig:
        return True

    timestamp = signature.get("timestamp", "")
    token = signature.get("token", "")

    expected = hmac.new(
        parent_signing_key.encode(),
        (str(timestamp) + str(token)).encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, parent_sig)


@app.get("/health")
async def health_check():
    return {"status": "ok"}


@app.post("/webhooks/mailgun")
async def handle_mailgun_webhook(request: Request):
    signing_key = os.getenv("MAILGUN_WEBHOOK_SIGNING_KEY")
    if not signing_key:
        raise HTTPException(
            status_code=500, detail="Webhook verification not configured"
        )

    body_bytes = await request.body()
    try:
        payload = json.loads(body_bytes)
    except json.JSONDecodeError:
        raise HTTPException(status_code=400, detail="Invalid JSON payload")

    signature: Optional[Dict[str, Any]] = payload.get("signature")
    if not signature:
        raise HTTPException(
            status_code=400, detail="Missing signature in request body"
        )

    if not verify_mailgun(signature, signing_key):
        raise HTTPException(status_code=400, detail="Invalid signature")

    parent_key = os.getenv("MAILGUN_PARENT_WEBHOOK_SIGNING_KEY")
    if signature.get("parent-signature") and parent_key:
        if not verify_parent_signature(signature, parent_key):
            raise HTTPException(
                status_code=400, detail="Invalid parent-signature"
            )

    event_data = payload.get("event-data")
    if not event_data or not event_data.get("event"):
        raise HTTPException(status_code=400, detail="Missing event-data")

    event = event_data["event"]
    recipient = event_data.get("recipient")

    if event == "accepted":
        print(f"Accepted: {recipient}")
    elif event == "rejected":
        reason = (event_data.get("reject") or {}).get("reason")
        print(f"Rejected: {recipient} - {reason}")
    elif event == "delivered":
        print(f"Delivered: {recipient}")
        # Mark message as delivered in your database
    elif event == "failed":
        # severity is 'permanent' (hard bounce) or 'temporary' (soft bounce)
        severity = event_data.get("severity")
        print(f"Failed ({severity}): {recipient}")
        if severity == "permanent":
            # Add address to your local suppression list
            pass
    elif event == "opened":
        print(f"Opened: {recipient}")
    elif event == "clicked":
        print(f"Clicked: {recipient} -> {event_data.get('url')}")
    elif event == "unsubscribed":
        print(f"Unsubscribed: {recipient}")
    elif event == "complained":
        print(f"Complained (spam): {recipient}")
    elif event == "stored":
        storage = event_data.get("storage") or {}
        print(f"Stored inbound message at {storage.get('url')}")
    elif event == "list_member_uploaded":
        print("List member uploaded")
    else:
        print(f"Unhandled event type: {event}")

    return JSONResponse(content={"received": True}, status_code=200)


if __name__ == "__main__":
    import uvicorn

    port = int(os.getenv("PORT", 3000))
    uvicorn.run(app, host="0.0.0.0", port=port)

From hookdeck/webhook-skills ↗

Or install the Mailgun webhooks skill:

npx skills add hookdeck/webhook-skills --skill mailgun-webhooks

Common failures

API key instead of the signing key

The key is the HTTP webhook signing key under Settings, then API Security. It isn't your API key or a domain sending key.

Subaccount events checked with the primary key

With only your primary account's key, verify signature.parent-signature. Mailgun adds it to events for a subaccount's domain so you don't need each subaccount's key.

Timestamp check too strict

Mailgun says webhook processing can be delayed for reasons outside its control, so don't be too aggressive when comparing timestamp with the current time.

A different Mailgun webhook

Inbound Routes send timestamp, token and signature as top-level form fields. A route URL ending in json uses X-Mailgun- headers and signs the body in place of token. Alert webhooks use X-Sign, sign the whole body and have their own key. Older legacy webhooks post form fields with a top-level event, and Mailgun says they all need migrating.

From Hookdeck's Mailgun guide

Let Event Gateway verify Mailgun signatures.

Event Gateway verifies the signature on each Mailgun delivery before it reaches your service, then queues it and retries failures on your schedule.

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