Webhooks for Transactional Emails

Webhooks are typically used to connect two different applications. When an event happens on the trigger application, it serializes the data about the respective event and sends it to a Webhook URL from the action application.

Features:

• Track user-level details such as delivered, open, click, unsubscribe, 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 email events in your own CRM

Set Up Webhook

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 up an optional secret key in the payload to validate the webhook events being sent on the callback URL.

Below is an example with header:

{
  "campaign_id": 0,
  "timestamp": 0,
  "event": "",
  "email": "",
  "msg-id": "",
  "event_type": "",
  "link_clicked": "",
  "reason": "",
  "campaign_name": "",
  "journey_name": "",
  "personalization_name": "",
  "variation_id": 0,
  "ins_unsub_id": 0,
  "unsub_group_name": "",
  "iid": "",
  "ip": "",
  "user_agent": "",
  "url_offset": null,
  "subject": ""
}

Webhook Events

Whenever there is an event, 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 by using the secret key (if applicable) after the first email is sent.

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
}

Deferred

A deferred event occurs when a server rejects the message temporarily. 

{
  "email": "sample@mail.com",
  "event": "deferred",
  "sender_domain": "@sender.domain",
  "msg-id": "51125925-a93e-4983-98be-29df277aa72c",
  "property1": "string",
  "property2": "string",
  "timestamp": 1603812854
}