Contents x
    Webhooks for Email Events
    • 01 Mar 2024
    • 5 Minutes to read
      Contents

      Webhooks for Email Events

      • Updated on 01 Mar 2024
      • 5 Minutes to read
        Article Summary

        As we process your email, webhook events will send information about any events that occur to a URL of your choice via HTTPS POST. 

        You can use this data to:

        • React to spam reports
        • Track email opens and clicks
        • Identify bounced email addresses
        • Create advanced analytics for your email program
        Your title goes here
        Event type selection is only available in Event Stream. Customers can select the events they want to get on their end. Customers can also get all events and attributes via Data Stream. Email webhook can send the default email events only.

        Get Started

        To set up webhooks for email events:

        1. Log in to Inone.
        2. Click Settings under the Log out menu.
        3. Select the Email Settings tab.
        4. Click the Webhook for Email Events button to enable webhooks. Add your callback URL. For further, refer to Secret Key.
        5. If you wish to use a secret key, add it now.
        6. Save changes.

        Please note that Secret key is an optional property that users can use while sending email to verify the webhook events. The key used in the payload is encrypted with the webhook event using SHA1 algorithm. The computed HMAC is sent back with the webhook events in X-INS-AUTH header. Users can verify the webhook events by decrypting the value returned under X-INS-AUTH.

        Below is an example with the header.

        {
  "campaign_id": 0,
  "timestamp": 0,
  "event": "",
  "email": "",
  "msg-id": "",
  "event_type": "",
  "link_clicked": "",
  "reason": "",
  "campaign_name": "",
  "journey_name": "",
  "sender_domain": "",
  "personalization_name": "",
  "variation_id": 0,
  "ins_unsub_id": 0,
  "unsub_group_name": "",
  "iid": "",
  "ip": "",
  "user_agent": "",
  "url_offset": null,
  "subject": ""
}
        your title goes here
        X-INS-AUTH header gets the result of encrypting event body with the provided secret key as its value.
        Your title goes here
        The special characters are URL encoded. For this reason, you need to decode the content with this in mind. Otherwise, you might get inconsistent results if you decode it before HASH comparison.

        Request

        You will receive an HTTPS POST containing a JSON array. The events will be pushed one after another as they are received from the server.

        Webhook Events

        Webhook events allow you to set up a notify URL on your callback server for reports. Unlike the API method, where reports are pulled and received in the response, webhook events send push reports to the notify URL you specify. Below are examples of webhook email events. Because events for Email and Architect journeys require different payloads, each example has two sections: Newsletter and Architect.

        The following are some of the most essential events:

        • Processed
        • Delivered
        • Blocked
        • Bounced
        • Email Open
        • Email Click
        • Unsubscribe
        • Group Unsubscribe
        • Spam Complaint
        • Deferred

        Processed

        A processed event is triggered when a message has been received and is ready to be delivered to the recipient.

        Email

        {
  "timestamp": 1614616711,
  "event": "processed",
  "email": "sample@mail.com",
  "campaign_name": "My campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 458,
  "subject": "My email subject",
  "iid": "5032a891-3a72-4dd8-be76-64c6a3e5a2ed"
}

        Architect

        {
  "timestamp": 1614674358,
  "event": "processed",
  "email": "sample@mail.com",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "variation_id": 406,
  "subject": "My email subject",
  "iid": "5032a891-3a72-4dd8-be76-64c6a3e5a2ed"
}

        Delivered

        A delivered event is triggered when a message is delivered to the recipient.

        Email

        {
  "timestamp": 1614617139,
  "event": "delivered",
  "email": "sample@mail.com",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 470,
  "subject": "My email subject",
  "iid": "6f5b2c74-12b6-44b0-b56e-1ade1aa13510",
  "ip": "11.22.333.444"
}

        Architect

        {
  "timestamp": 1614674360,
  "event": "delivered",
  "email": "sample@mail.com",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "variation_id": 406,
  "subject": "My email subject",
  "iid": "6f5b2c74-12b6-44b0-b56e-1ade1aa13510",
  "ip": "111.22.333.444"
}

        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

        {
  "email": "sample@mail.com",
  "event": "bounce",
  "event_type": "blocked",
  "reason": "unable to get mx info: lookup <nil>: unrecognized address",
  "campaign_name": "My Email",
  "sender_domain": "@sender.domain",
  "timestamp": 1563890443,
  "iid": "80147815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Architect

        {
  "email": "sample@mail.com",
  "event": "bounce",
  "event_type": "blocked",
  "reason": "unable to get mx info: lookup <nil>: unrecognized address",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "timestamp": 1563890443,
  "iid": "80147815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Bounced

        A bounced event is triggered when a hard bounce is received from the receiving server for a specific email ID. The reason for bounce will also return in the payload.

        Email

        {
  "email": "sample@mail.com",
  "event": "bounce",
  "reason": "unable to get mx info: lookup <nil>: unrecognized address",
  "campaign_name": "My Email",
  "sender_domain": "@sender.domain",
  "timestamp": 1563890443,
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Architect

        {
  "email": "sample@mail.com",
  "event": "bounce",
  "reason": "unable to get mx info: lookup <nil>: unrecognized address",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "timestamp": 1563890443,
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Email Open

        An open event is triggered when a recipient opens an email.

        Email

        {
  "timestamp": 1614617141,
  "event": "open",
  "email": "sample@mail.com",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 4868,
  "subject": "My email subject",
  "iid": "5055a891-3a72-4dd8-be76-64c3a3e5a2ed",
  "ip": "111.22.333.444",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 Lightning/68.10.0"
}

        Architect

        {
  "timestamp": 1614674362,
  "event": "open",
  "email": "sample@mail.com",
  "journey_name": "My Journey",
  "personalization_name": "My Journey Email 1",
  "sender_domain": "@sender.domain",
  "variation_id": 4906,
  "subject": "My email subject",
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "ip": "11.222.33.44",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0"
}

        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

        {
  "timestamp": 1614617637,
  "event": "click",
  "email": "sample@mail.com",
  "link_clicked": "https://mywebsite.com/link",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 4872,
  "subject": "My email subject",
  "iid": "4331e457-21b4-4783-961a-71f24615a57a",
  "ip": "111.222.333.444",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.150 Safari/537.36",
  "url_offset": {
    "index": 0,
    "type": "html"
  }
}

        Architect

        {
  "timestamp": 1614678551,
  "event": "click",
  "email": "sample@mail.com",
  "link_clicked": "https://mywebsite.com/link",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "variation_id": 4906,
  "subject": "My email subject",
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "ip": "11.22.33.44",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.83 Safari/537.36",
  "url_offset": {
    "index": 0,
    "type": "html"
  }
}

        Unsubscribe

        An unsubscribe webhook event is triggered when a recipient clicks the unsubscribe link in an email campaign.

        Email

        {
  "timestamp": 1614617242,
  "event": "unsubscribe",
  "email": "sample@mail.com",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 4870,
  "subject": "My email subject",
  "iid": "8bbf825f-9c19-425a-8144-db6dc19f91ca"
}

        Architect

        {
  "email": "sample@mail.com",
  "event": "unsubscribe",
  "reason": "Unsubscribed Address",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "timestamp": 1562591800,
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Group Unsubscribe

        A group unsubscribe webhook event is triggered when a recipient clicks the unsubscribe link for a specific unsubscribe group.

        Email

        {
  "timestamp": 1603469700,
  "event": "group_unsubscribe",
  "email": "sample@mail.com",
  "msg-id": "",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 22,
  "subject": "My email subject",
  "iid": "8bbf825f-9c29-425a-9144-db6dc19f91ca",
  "ins_unsub_id": "group id"
}

        Spam Complaint

        A spam-complaint event is triggered when a recipient marks an email as spam.

        Email

        {
  "email": "sample@mail.com",
  "event": "spam_complaint",
  "campaign_name": "My Email",
  "sender_domain": "@sender.domain",
  "timestamp": 1564224981,
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Architect

        {
  "email": "sample@mail.com",
  "event": "spam_complaint",
  "journey_name": "My Journey",
  "sender_domain": "@sender.domain",
  "personalization_name": "My Journey Email 1",
  "timestamp": 1564224981,
  "iid": "80257815-d6c1-459d-9edb-2f3456d4179b",
  "variation_id": 1234,
  "subject": "My email subject"
}

        Deferred

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

        Email

        {
  "timestamp": 1603628469,
  "event": "deferred",
  "email": "sample@mail.com",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 211,
  "subject": "My email subject",
  "iid": "8bbf815f-9c19-427a-9144-db3dc18f91ca"
}

         Architect

        {
  "timestamp": 1603628469,
  "event": "deferred",
  "email": "sample@mail.com",
  "campaign_name": "My Campaign",
  "sender_domain": "@sender.domain",
  "variation_id": 211,
  "subject": "My email subject",
  "journey_name": "My Journey",
  "personalization_name": "My Journey Email 1",
  "iid": "8bbf825f-9c19-426a-9144-db6dc18f11ca"
}
        Was this article helpful?
        Related articles
        What's Next
        ESC

        Eddy, a super-smart generative AI, opening up ways to have tailored queries and responses