Webhooks are typically used to connect two different applications. When an event occurs in the trigger application, it serializes the event data and sends it in real time to a Webhook URL on the action application.
Webhooks offer several features that enhance functionality and data management:
Track user-level details such as delivered, open, click, unsubscribe, and marked as spam.
Synced and consistent database of real-time user interactions with emails.
Webhooks email reporting (invalid email IDs, bounce backs) for improved list/database hygiene.
Automatic and manual user segmentation using real-time email events in your own CRM.
Both API v1 and API v2 are supported, and V1 remains supported until summer 2027. The two versions differ only in where you configure the callback. Signature verification and the event payloads below are shared.
Set up callback
Callback configuration depends on the API version.
API Version | Where | Applies to | Secret |
|---|---|---|---|
Once in the panel | Every transactional email sent from the account | Required | |
A callback object in each send payload | The respective request only | Optional |
V2: Configure in the panel
Unlike V1, the callback URL and secret are not part of the send payload in V2. You configure them once in the panel, and they apply to every transactional email sent from that account.
Before you start
Your endpoint must be publicly reachable over HTTPS and return a 2xx response within 30 seconds.
Custom authentication headers are not supported. Use the secret-based HMAC signature described in Verifying the signature to verify authenticity.
Configuration
In the panel, go to Settings > Email Settings > Webhook Integration for Transactional Email.
Select Enable Webhook Integration for Transactional Email. The Callback URL and Secret fields are hidden until this is enabled.
Enter your Callback URL. It must be a valid URL; an empty or malformed value is rejected.
Enter your Secret. Unlike V1, the secret is required in V2 and cannot exceed 256 characters. It is stored encrypted and is never returned in plaintext.
Click the Save button to save your changes.
This section is independent of the classic Webhook for Email Events block on the same page. Configuring one does not affect the other.
Verify your setup
Point the Callback URL at a test collector (e.g., webhook.site), send a test email through the V2 API, and confirm you receive a processed event carrying the same msg-id as the message_id returned by the send request.
V1: Callback object in the payload
You can set up the callback within the body payload to receive webhook events for your transactional emails by adding the following sample object at the end of the payload:
"callback": {
"url": "https://webhook.site/123abc-4567-890d-a1b2-3c4d5e6f7g",
"secret": "secret"
}
You can also set an optional secret key in the payload to validate webhook events sent to the callback URL. The Secret key is an optional property in V1 that users can use while sending an email to verify the webhook events.
Verify the signature
Every event is POSTed as JSON with Content-Type: application/json. Insider computes an HMAC of the request body using your secret and sends it in two headers:
Header | Algorithm | Format |
|---|---|---|
X-INS-AUTH | HMAC-SHA1 | sha1=<hex digest> |
X-INS-AUTH-512 | HMAC-SHA512 | sha512=<hex digest> |
Compute the HMAC over the raw, unparsed request body, and compare the result using a constant-time comparison.
The content is encoded with UTF-8 on our end. Therefore, we suggest using the same encoding when reading the data stream to prevent interoperability issues. For example, reading with UTF-16 or Unicode might create problems with Unicode characters. The programming language we are using implements JSON encoding, as covered in sections 8.1 and 8.2 of the RFC.
Webhook events
Whenever an event occurs, webhook events will notify a URL of your choice via HTTPS POST. Webhook events will provide information about the event and return a unique message ID (msg-id) generated to map the emails associated with the event while also hitting the API. Webhook events will be delivered to the provided endpoint and encrypted using the secret key (if applicable) after the first email is sent.
Custom arguments in the event body
Any keys you pass with the send request, unique_args in V2, are merged into the event body. This is why the samples below carry keys such as property1 and product1. The reserved fields event, email, uuid, msg-id, reason, and timestamp always take precedence and cannot be overridden.
The following are some of the most essential events:
Processed
Delivered
Blocked
Bounced
Email Open
Email Click
Spam Complaint
Dropped
Deferred
Processed
A processed event is triggered when a message has been received and is ready to be delivered to the recipient.
{
"email": "sample@mail.com",
"event": "processed",
"sender_domain": "@sender.domain",
"msg-id": "389c9e3a-6c39-4e0e-b559-ab174321fdc5",
"property1": "string",
"property2": "string",
"timestamp": 1603813206
}Delivered
A delivered event is triggered when a message is delivered to the recipient.
{
"email": "sample@mail.com",
"event": "delivered",
"sender_domain": "@sender.domain",
"ip": "111.22.333.444",
"msg-id": "bd12fbea-f982-4d8d-8378-04b23125a185",
"product1": "laptop",
"product2": "phone",
"timestamp": 1614700548
}Blocked
A blocked event is triggered when a soft bounce (blocked) is received from the receiving server for a specific email ID. The reason for the soft bounce will also return in the payload.
{
"email": "sample@mail.com",
"event": "bounce",
"event_type": "blocked",
"sender_domain": "@sender.domain",
"msg-id": "51144895-a93e-4983-98be-29--34df377aa52c",
"property1": "string",
"property2": "string",
"reason": "error dialing remote address: dial tcp 111.22.333.444:0->55.666.777.888:99: i/o timeout",
"timestamp": 1603813274
}Bounced
A bounced event is triggered when a hard bounce is received from the receiving server for a specific email ID. The reason for the hard bounce will also return in the payload.
{
"email": "sample@mail.com",
"event": "bounce",
"sender_domain": "@sender.domain",
"msg-id": "c289bc4f-410f-2b83-a76e-f75f5cc67afd",
"reason": "unable to get mx info: lookup <nil>: unrecognized address",
"product1": "laptop",
"product2": "phone",
"timestamp": 1563890445
}Email Open
An open event is triggered when a recipient opens an email.
{
"email": "sample@mail.com",
"event": "open",
"sender_domain": "@sender.domain",
"ip": "11.222.33.444",
"msg-id": "bd16fbea-f982-2d8d-8378-04b12125a185",
"product1": "laptop",
"product2": "phone",
"timestamp": 1614700573,
"url_offset": null,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36"
}Email Click
A link click event is triggered when a recipient clicks a link in the email. The clicked link will also be sent with the webhook event.
{
"email": "sample@mail.com",
"event": "click",
"sender_domain": "@sender.domain",
"ip": "11.222.33.444",
"link_clicked": "https://www.mywebsite.com/link-html",
"msg-id": "bd16fbea-f982-4d4d-8378-04b12125a185",
"product1": "laptop",
"product2": "phone",
"timestamp": 1614700422,
"url_offset": {
"index": 0,
"type": "html"
},
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36"
}Spam Complaint
A spam-complaint event is triggered when a recipient marks an email as spam.
{
"email": "sample@mail.com",
"event": "spam_complaint",
"sender_domain": "@sender.domain",
"msg-id": "c383bc4f-640f-4b83-a76e-f75f3cc67afd",
"product1": "laptop",
"product2": "phone",
"timestamp": 1563890445
}Dropped
A drop event occurs when you try to send a message to an email address listed on one of the suppression lists: bounces, unsubscribes, spam reports, and invalid emails.
{
"email": "sample@mail.com",
"event": "dropped",
"sender_domain": "@sender.domain",
"msg-id": "51154935-a93e-4983-98be-29df237aa52c",
"property1": "string",
"property2": "string",
"reason": "Bounced Address",
"timestamp": 1603812824
}Dropped: unresolved UUID (V2)
A drop is also triggered when a recipient is identified only by uuid and no matching profile exists in the Unified Customer Database (UCD). What happens next depends on whether a callback is configured:
Callback configured | Result |
|---|---|
Yes | A dropped event is POSTed to your Callback URL. No UCD profile is created. |
No | The drop is recorded in the UCD, and a profile is created for the UUID. |
{
"event": "dropped",
"email": "",
"uuid": "iid-12345",
"msg-id": "b7f3c1a2-...",
"reason": "uuid-resolution-failed:not-found",
"timestamp": 1770000000,
"order_id": "ORD-456"
}Deferred
A deferred event occurs when a server temporarily rejects a message.
{
"email": "sample@mail.com",
"event": "deferred",
"sender_domain": "@sender.domain",
"msg-id": "51125925-a93e-4983-98be-29df277aa72c",
"property1": "string",
"property2": "string",
"timestamp": 1603812854
}