Launch special — let's split the check with SPLITCHECK for 50% off
Share feedback →

Mailgun Webhooks

How to Test Mailgun Webhooks Locally (2026)

Mailgun sends webhooks for email delivery events — delivered, opened, clicked, bounced, complained, unsubscribed. Mailgun's signature isn't a header: each payload includes a signature object (timestamp, token, signature) where signature is an HMAC-SHA256 of timestamp+token using your HTTP webhook signing key.

Signature Header

(in body: signature object)

Algorithm

HMAC-SHA256 of timestamp+token (HTTP webhook signing key)

Setup Guide

  1. 1Create a free HookSense endpoint at hooksense.com
  2. 2Copy your unique webhook URL
  3. 3In the Mailgun dashboard → Send → Webhooks → Add webhook
  4. 4Choose an event type and paste your HookSense URL
  5. 5Copy the HTTP webhook signing key from Settings → Webhooks (not your API key)
  6. 6Send a test event from the dashboard
  7. 7Watch the payload — including the signature object — land in HookSense

Common Mailgun Webhook Events

delivered
opened
clicked
unsubscribed
complained
permanent_fail
temporary_fail
stored

Forward to Localhost

Use HookSense CLI to forward Mailgun webhooks directly to your local development server:

npx hooksense listen -p 3000 --path /api/integrations/mailgun

No ngrok or tunnel setup required. Install with npm i -g hooksense or use npx.

Tips & Best Practices

  • Mailgun's signature lives in the body, not a header: HMAC-SHA256 of (timestamp + token) keyed by the HTTP webhook signing key
  • The signing key is separate from your API key — find it under Settings → Webhooks
  • Cache the token and reject duplicates to prevent replay attacks; loosely check the timestamp for freshness
  • Use HookSense Replay to retest delivery and bounce handling without sending real email

Related

Mailgun Webhook Documentation HMAC Signature Calculator HMAC Verification Guide HookSense Documentation

Start Testing Mailgun Webhooks

Create a free endpoint and receive your first Mailgun webhook in seconds.

Get Started Free