Overview

Webhooks allow your application to programmatically receive information in near real-time whenever an event happens on your Mailgun account. This allows your application to stay up to date on everything that happens with the email messages you send.

Use cases for webhooks can include:

• Storing events in your own or 3rd party application for reporting purposes
• Removing recipient addresses that bounce, complain or unsubscribe (good email hygiene!)
• Triggering fallback channels like SMS or push notifications when critical transactional emails fail to deliver
• Building engagement profiles from open and click data to optimize send frequency and audience segmentation
• Maintaining compliance and audit trails for industries with regulatory requirements around email delivery records
• Surfacing delivery status to end users on platforms that send email on behalf of their customers
• Syncing engagement data with CRM tools so sales teams can see if prospects opened their emails

Configuring Webhooks

Webhooks can either be configured at the domain level or at the account level, enabling you to set unique endpoints for each domain or fire an event for any of your domains/subaccounts to simplify setup. Each event type is configured individually and can contain up to 3 URLs per event type.

We recommend using http://bin.mailgun.net/ for creating temporary URLs to test and debug your webhooks.

Webhooks can be found within the Mailgun application on the left-hand nav under Send > Sending > Webhooks:

Domain-Level Webhooks

Domain-level webhooks will only fire when an event happens for the domain it is configured for. 

To configure domain-level webhooks, click on the Add webhook button in the upper right hand corner and select Domain-level:

On the modal that pops up, choose a description so that you can identify your webhook later, provide your URL endpoint you want the webhook events delivered to, select the event types and choose the domain you wish to configure the webhook for and then click Create webhook.

Account-Level Webhooks

Account level webhooks will fire when an event happens on any of the domains belonging to that account or subaccount(s).

To configure account-level webhooks, click on the Add webhook button in the upper right hand corner and select Account-level:

On the modal that pops up, choose a description so that you can identify your webhook later, provide your URL endpoint you want the webhook events delivered to, select the event types and and then click Create webhook.

Regions

Regions are isolated, meaning you will need to create distinct webhooks in each region for the account/domains.

Deduplication and Other Considerations

If you configure the same URL for the same event at both the domain level and account level, Mailgun treats that as a duplicate and will only send the event once. This prevents your endpoint from receiving multiple copies of the same event. Here are some other considerations:

• Deduplication: Events are delivered once to each unique URL configured at any level. Same URL at domain and account level = send account-level only
• Account inheritance: If an account level webhook is configured on the primary account and an event happens on a domain that belongs to a subaccount, the account level webhook will fire
• Scope isolation: Subaccount webhooks don't affect primary account webhook delivery

PII Redaction

Enterprise and InfoSec companies may wish to redact Personally Identifiable Information (PII) for their webhooks, and this is possible within Mailgun. By enabling this setting, Mailgun will redact everything it considers to be PII. 

PII redaction is an account-level setting that can be configured both in the Control Panel and through the Account Management/Account Features API endpoint. If account-wide PII redaction is not desired, customers can enable this feature for specific domains via the Domains API; the ability to configure domain-specific PII redaction is not currently available in the Control Panel. (For even more details, please see the User Manual).

General technical details to understand:

• The redaction takes place just before we attempt to deliver the webhook to its destination.
• We use a placeholder such as [REDACTED] over values that we deem as PII and redact.
• The message-id field remains intact to ensure ease-of-use when researching and troubleshooting specific messages.
• You must opt-in to use this feature; it's not enabled on your account by default.

Depending on the type of webhook (i.e. which event the webhook corresponds to), we redact specific fields. The table below contains a list of what we redact in webhooks by each Event type:

What About User Variables?
We considered including user variables in the redaction process. However, the chief concern is that customers often utilize user variables to correlate the webhook events with their internal systems. If we remove or redact them entirely, customers may lose the ability to map events back to their own records, with the only alternative being to rely solely on the message-id field.

Use subaccounts?

If your account does utilize subaccounts, the toggle option will appear like below on the Configuration screen within the Primary/Parent account to enable the feature account-wide: all domains on the Primary/Parent account as well as all domains on all subaccounts. In other words, subaccounts inherit the account-wide setting. As an aside, subaccounts will not have visiblity of or access to configure the PII optiion within their Control Panel.

Don't use subaccounts?

If your account does not utilize subaccounts, the toggle option will appear like below on the Configuration screen to enable the feature account-wide for all domains on the account.

Webhook Failure Logs

Mailgun maintains logs for failed attempts to POST to your webhook endpoint. You can find these logs under the Failure logs tab on the Webhooks page. This page will include the timestamp, the URL we attempted to POST to and the Failure reason:

Webhook Retries

For Webhook POSTs, Mailgun listens for the following codes from your server and reacts accordingly:

• If Mailgun receives a 200 (Success) code it will determine the webhook POST is successful and not retry.
• If Mailgun receives a 406 (Not Acceptable) code, Mailgun will determine the POST is rejected and not retry.
• For any other code, Mailgun will retry POSTing according to the following schedule (other than the delivery notification): 10 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hour and 4 hours.

Finally, we recommend our webhooks user manual for other information regarding webhooks.

Need Support?

Our Support Team here at Sinch Mailgun is happy to help! Reach out to us in the Support page of your Mailgun Control Panel, and we'll be with you shortly!