Mailgun webhooks provide real-time notifications about email events including deliveries, bounces, complaints, opens, clicks, and unsubscribes. They are critical for monitoring email deliverability and engagement.
Mailgun webhooks are HTTP POST requests that Mailgun sends to your server when specific events occur in your account. Rather than continuously polling the Mailgun API for updates, webhooks deliver real-time notifications the moment something happens — a payment completes, a user signs up, a deployment finishes, or any other tracked event.
Debugging these webhooks can be challenging because they originate from Mailgun's servers, not your browser. You can't simply open DevTools to inspect them. That's where WebhookVault comes in — capture every Mailgun webhook, inspect the full payload and headers, and replay them to your local development server.
| Event | Description |
|---|---|
| delivered | Fired when an email is successfully delivered to the recipient's server |
| permanent_fail | Fired when an email permanently bounces (invalid address, etc.) |
| opened | Fired when a recipient opens an email |
| complained | Fired when a recipient marks an email as spam |
Follow these steps to start capturing and debugging Mailgun webhooks using WebhookVault.
Sign up for a free WebhookVault API key and create an endpoint to capture Mailgun webhooks.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "Mailgun Webhooks"}'
# Response:
# {"url": "https://webhookvault.anethoth.com/hook/abc123", "inspect_url": "https://webhookvault.anethoth.com/inspect/abc123"}Go to the Mailgun Dashboard > Sending > Webhooks Select the domain you want to configure webhooks for Click on the event type and enter your WebhookVault endpoint URL Save and test using Mailgun's 'Test Webhook' feature
Once Mailgun sends a webhook, you can inspect every detail through the WebhookVault API or web inspector.
curl https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests \
-H "Authorization: Bearer wv_your_key"
# Returns all captured Mailgun webhook requests with full headers, body, and metadataReplay any captured Mailgun webhook to your local development server for testing.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests/1/replay \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "http://localhost:3000/webhook"}'
# The original Mailgun webhook is replayed to your local serverHere is an example of a typical Mailgun webhook payload. Use WebhookVault to capture real payloads from your Mailgun account for accurate testing.
{
"signature": {
"token": "abc123def456",
"timestamp": "1706000000",
"signature": "hmac_sha256_signature_here"
},
"event-data": {
"event": "delivered",
"timestamp": 1706000000,
"recipient": "[email protected]",
"message": {
"headers": {
"message-id": "abc123.mailgun.org",
"subject": "Welcome to Our Service"
}
},
"delivery-status": {
"code": 250,
"message": "OK"
}
}
}Here are the most common issues developers encounter when working with Mailgun webhooks, and how to resolve them.
Mailgun includes a signature object with token, timestamp, and HMAC-SHA256 signature. Verify using your Mailgun API key.
Mailgun has legacy and current webhook formats. Ensure you're parsing the correct format based on your account settings.
Different events can be routed to different webhook URLs. Configure each event type's URL separately in the dashboard.
Check the timestamp in the signature to prevent replay attacks. Reject events older than a reasonable threshold.
Mailgun webhooks are HTTP callbacks that Mailgun sends to your server when specific events occur. Instead of polling the Mailgun API for changes, webhooks push real-time notifications to your application, making your integration more efficient and responsive.
Use WebhookVault to capture Mailgun webhooks in the cloud, then replay them to your localhost. Create a WebhookVault endpoint, configure Mailgun to send webhooks to it, and use the replay API to forward captured requests to http://localhost:3000/webhook (or your local port).
Most webhook providers, including Mailgun, sign their webhook payloads to prove authenticity. Check the Mailgun documentation for the specific signature header and verification algorithm. Use WebhookVault to capture and inspect the raw headers to debug signature verification issues.
Unlike ngrok, WebhookVault captures and stores every webhook request with full headers and payloads. You can replay any Mailgun webhook to your local server as many times as needed, inspect historical requests, and share webhook data with your team. No tunnel to maintain or port to expose.
Create a free WebhookVault endpoint in seconds. Capture, inspect, and replay Mailgun webhooks with zero configuration.
Get Free API Key