Webhooks
The basics
Webhooks allow your application to receive information about email events as they occur and respond in a way that you define. This documentation will detail configuring and testing webhooks, as well as information about authentication, failed batches, message formats, and more. To walk through the basic process of setting up a webhook, check out the Track and Respond to Email Activity with Webhooks guide.
Formats
Every Mailchimp Transactional webhook uses the same general data format, regardless of the event type. The webhook request is a standard HTTP POST request with a single parameter: mandrill_events.
There are three types of webhooks that Mailchimp Transactional currently POSTs:
Message events: send, deferral, hard-bounce, soft-bounce, delivered, open, click, spam, unsub, reject
Sync events: allowlist or denylist sync
Inbound messages
The mandrill_events parameter contains a JSON array of webhook events, up to a maximum of 1,000 events. Each element in the array is a single event, such as an open, click, or denylist sync event.
Note: Webhooks are sent to your app via an HTTP POST request. You can and should authenticate that webhooks originated from Mailchimp’s servers by following the steps laid out in the “Authenticating webhook requests” section of the webhooks guide.
Event types
Message event webhooks can be triggered by several types of events:
Sent: message has been sent successfully
Opened: recipient opened a message; will only occur when open tracking is enabled
Clicked: recipient clicked a link in a message; will only occur when click tracking is enabled
Delivered: message has received a response from the recipient’s mail server indicating successful delivery
Delayed: message has been sent, but the receiving server has indicated mail is being delivered too quickly and Mailchimp Transactional should temporarily slow down sending
Marked as Spam: recipient marked a message as spam
Bounced: message has hard-bounced
Soft-Bounced: message has soft-bounced
Recipient Unsubscribes: recipient has unsubscribed
Rejected: message was rejected
Sync event webhooks allow you to sync data to an external data source. They help you track changes to data stored in Mailchimp Transactional, including:
Rejection Denylist Changes: triggered when a Rejection Denylist entry is added, changed, or removed
Rejection Allowlist Changes: triggered when a Rejection Allowlist entry is added or removed
Inbound messages are processed based on the routes you’ve set up, and messages matching those routes are sent to your specified URL(s) as a webhook. For more information on inbound email, see the Set Up Inbound Email Processing guide.
Add a new webhook
You can configure a new webhook via your Mailchimp Transactional account or using the Transactional API.
In the app:
Navigate to Webhooks and click Add a Webhook at the top of the page
Choose the events you want to listen for in the “Trigger on Events” section (e.g., when an email is sent, bounces, is opened, is marked as spam, is clicked)
In the “Post To URL” field, input the callback URL your application will use to accept the incoming webhook
Give your webhook an optional description under Description
Click Create Webhook
With the API:
Send a POST request to the webhooks/add endpoint. For example:
Add a new webhook
{
"key": "YOUR_API_KEY",
"url": "http://example.com/webhook-url",
"description": "My Example Webhook",
"events": [
"send",
"open",
"click",
"hard_bounce",
"spam"
]
}Note: Your webhook callback URL should be set up to accept POST requests at a minimum. When you provide the URL where you want Mailchimp to POST the event data, a HEAD request will be sent to the URL to check that it exists.
If the URL doesn't exist or returns something other than a 200 HTTP response to the HEAD request, Mailchimp will fall back and attempt a POST request. In this case, the POST request’s mandrill_events parameter will be an empty array, and the POST will be signed with a generic key (with the value test-webhook).
Test and debug webhooks
You can send test events to any outbound webhook URL in your Mailchimp Transactional account using our built-in testing tools. In the Webhooks section, find the webhook you’d like to test and click the send test button to send a batch of events to your webhook URL.
If your webhook is set to trigger on more than one event type (e.g., open and click), the test will send one event for each type you’ve selected. If your webhook is set to trigger on only one event type, the test will send two events for that type. If the POST succeeds, we’ll display a success message that includes the number of POSTed events. If the POST fails, you’ll see an error message with more details on the failure.
If you want to test webhooks in an external or temporary environment before making changes in production, check out these third-party tools:
Failed webhook batches
Mailchimp Transactional batches events for each webhook URL and POSTs approximately once per minute. If the webhook URL does not return a 200 HTTP response code, the POST request will be re-attempted up to 20 times at 15-25 minute intervals. After 20 attempts, it will be considered a failure and will be marked as such in the app.
While an unsuccessful POST request is being re-attempted, no other POSTs will be attempted. Subsequent events will be batched and deferred until the first event succeeds or ultimately fails. After the first event completes, deferred batches will be processed sequentially.
To avoid data loss, we recommend that you accept and store data (with an HTTP 200 response to Mailchimp) for later processing.
If your webhook has encountered too many failures, it will be disabled by having the triggers removed. Once you’ve resolved the connection issue, you can add the desired triggers back in the Webhooks page in your account.
View failed batches
For webhooks in an error state, Mailchimp provides the raw webhook request content and sample code so you can emulate the failed POST using cURL.
To view webhook batch details, navigate to Webhooks, click on the number shown under Number of events, and then click the view batch button. At the top of the page, you’ll see the raw webhook request generated and sent by Mailchimp Transactional. You can use the cURL command at the bottom of the page to mimic the webhook POST in your own environment.
Note: If the webhook payload is too large to fit on the common command line, we will provide a link to download it in full as a .txt file. You’ll need to save the file in your working directory before you run the cURL command.
Stop failed batches manually
While Mailchimp automatically re-attempts failed webhook batches, you can also stop a failed batch manually. Navigate to Webhooks, click on the number shown under Number of events, and then click give up.The batch will be stopped and will not be sent to the webhook URL. New events will begin posting in about one to two minutes.
Detailed webhook format responses
Each type of webhook sends a slightly different payload to your server when it fires. The following charts detail the keys included with each type of event.
Message events
the integer UTC UNIX timestamp when the event occurred
the name of the event, one of: send, deferral, hard_bounce, soft_bounce, delivered, open, click, spam, unsub, reject
for click events only, the url clicked for the event
for open and click events only, the IP address where the event originated
for open and click events only, the user agent string for the environment (i.e., browser or email client) where the open or click occurred
for open and click events only, the geolocation where the event occurred. Value will be null if no location can be determined from the IP address of the event. Otherwise, an array of key–value pairs with the following keys:
for open and click events only, a parsed version of the user agent detected for the event. Value will be null if the user agent can’t be determined. Otherwise, an array of key–value pairs with the following keys:
the unique identifier of the message that generated the event. This is not an event identifier, but rather a reference to the message ID for the email that was sent, opened, clicked, etc.
details about the message for which the event occurred. May be empty if the message that generated an open or click is older than 30 days, or when the message was not yet indexed when the event occurred.
Sync events
the integer UTC UNIX timestamp when the event occurred
the list that the sync event applies to (allowlist or denylist)
the name of the event. Possible values: add (allowlist or denylist), remove (allowlist or denylist), change (denylist only)
Inbound messages
the integer UTC UNIX timestamp when the event occurred
the name of the event
details about the message for which the event occurred
the full content of the received message, including headers and content
an array of the headers received for the message, such as "Dkim-Signature", "Mime-version", "Date", "Message-Id", etc.
the plain text version of the message
the HTML version of the message
the message sender's email address
the message sender's name
the email addresses and names of the recipients of the message
the email address where Mailchimp Transactional received the message
the subject line of the message
the tags applied to the message; inbound messages won’t have tags, since they’re being received instead of sent, so this should always be an empty array
In inbound, sender will always show as null
an array of attachments for the message, with filenames as keys. If there are no attachments, this key is omitted. Each attachment has the following keys:
an array of images for the message, with filenames as keys. If there are no images, this key is omitted. Each image has the following keys:
the results of processing the message with the default SpamAssassin rules. Contains the following key:
an array of objects containing details about the rules that the message matched. Each rule entry contains the following keys: