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

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!