Articles in this section

System Webhooks

A system webhook sends data from Iterable to a third-party system whenever a specified event occurs (for example, an email send, an email open, etc.).

Each system webhook is specific to an Iterable project, but not to a particular template, campaign, or journey. The webhook will fire whenever a particular event occurs anywhere in the project.

NOTE

We recently renamed Workflows to Journeys—however, our APIs and field names still refer to them as "Workflows" (for example, workflowId). Continue to use the term "Workflows" in your API requests and responses.

To call a webhook as part of a specific journey, use a journey webhook.

Setting up a system webhook

To set up a system webhook:

  • Navigate to Integrations > System Webhooks.

  • Click Create Webhook to bring up the system webhook creation form:

    Creating a system webhook

  • Enter the Webhook URL and click Create Webhook.

    IMPORTANT

    All webhooks defined in Iterable must use HTTPS-based URLs. Starting June 30th, 2022, webhooks that rely on HTTP URLs will fail. For more information, read these release notes.

    A limited set of merge parameters can be used in the webhook's URL:

    • campaignId
    • campaignName
    • templateId
    • templateName
    • channelId
    • workflowId
    • workflowName
    • experimentId
    • messageTypeId

    For example:

    https://hookb.in/XXXXXX?src=iterable&cname={{campaignName}}&cid={{campaignId}}

    If any of these parameters are not defined when the webhook is called, they will render as blank.

  • Click Create Webhook to configure the webhook.

    Configuring a system webhook

  • To activate the webhook, set Status to Enabled.

  • Choose an Authentication type.

  • To add request headers to the webhook, click Add HTTP Header as necessary.

  • Select the webhook's triggering events:

    Selecting webhook triggers

  • Click Save.

Webhook request headers

A webhook sends a POST request with the following headers:

  • Content-Type: application/json

  • Authorization: <authType> <authToken>

    For example:

    • Selecting Basic for Auth Type and providing an Auth Token of XXXXXXXXXXXXXXXXXXXXXXXXXXX yields the following authorization header:

      Authorization: XXXXXXXXXXXXXXXXXXXXXXXXXXX

    • Selecting OAuth2 for Auth Type and providing an Auth Token of XXXXXXXXXXXXXXXXXXXXXXXXXXX would yield the following authorization header:

      Authorization: OAuth2 XXXXXXXXXXXXXXXXXXXXXXXXXXX

    NOTE

    If you select an Auth Type of NoAuth, the webhook request does not include an Authorization header.

Webhook request body

The body of a webhook request contains the following fields:

  • email - The email address associated with the event
  • eventName - The name of the event for which a webhook has been triggered
  • dataFields - An object that contains fields related to the webhook's triggering event.

For detailed webhook request bodies, see Webhook examples.

Error handling

TIP

After creating a system webhook in Iterable, test it to make sure it works as expected. Do this before sending any campaigns that rely on it.

Iterable does not guarantee the successful delivery of system webhooks.

If a system webhook request fails, Iterable makes several retry attempts in the following minutes. If the retries are also unsuccessful, the event is dropped.

Iterable may duplicate successful system webhook requests. For example, this can sometimes happen when a request is retried after a timeout.

Iterable disables system webhooks for which there is a sustained, elevated error rate. After you resolve the issue, re-enable the system webhook on the Integrations > System Webhooks page.

If your system webhook endpoint uses a certificate signed by a certificate authority not trusted by Iterable, Iterable's system webhook calls to that endpoint will fail. Iterable recognizes the certificate authorities listed by Mozilla on CA/Included Certificates.

Webhook examples

Below, find example webhook requests for various event types:

Blast Send

{
  "email": "user@example.com",
  "eventName": "emailSend",
  "dataFields": {
    "contentId": 331201,
    "email": "user@example.com",
    "createdAt": "2016-12-02 20:21:04 +00:00",
    "campaignId": 59667,
    "templateId": 93849,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "emailId": "c123456:t456789:user@example.com"  
}

Email Bounce

{
  "email": "user@example.com",
  "eventName": "emailBounce",
  "dataFields": {
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 2598,
    "messageTypeId": 2870,
    "experimentId": null,
    "recipientState": "HardBounce",
    "templateId": 167484,
    "email": "user@example.com",
    "createdAt": "2017-05-15 23:59:47 +00:00",
    "campaignId": 114746,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailId": "c123456:t456789:user@example.com"
  }
}

Email Click

{
  "email": "user@example.com",
  "eventName": "emailClick",
  "dataFields": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36",
    "ip": "162.245.22.184",
    "templateId": 93849,
    "userAgentDevice": "Mac",
    "url": "https://www.iterable.com",
    "canonicalUrlId": "3145668988",
    "city": "San Francisco",
    "region": "CA",
    "email": "user@example.com",
    "createdAt": "2016-12-02 20:31:39 +00:00",
    "campaignId": 59667,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "linkUrl": "https://www.iterable.com",
    "linkId": "3145668988",
    "emailId": "c123456:t456789:user@example.com"
  }
}

Email Complaint

{
  "email": "user@example.com",
  "eventName": "emailComplaint",
  "dataFields": {
    "recipientState": "Complaint",
    "templateId": 79190,
    "email": "user@example.com",
    "createdAt": "2016-12-09 18:52:19 +00:00",
    "campaignId": 49313,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "test template",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "emailId": "c123456:t456789:user@example.com"
  }
}

Email Open

{
  "email": "user@example.com",
  "eventName": "emailOpen",
  "dataFields": {
    "userAgent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
    "proxySource": "Gmail"
    "ip": "66.249.84.204",
    "templateId": 79190,
    "device": "Gmail",
    "email": "user@example.com",
    "createdAt": "2016-12-02 18:51:45 +00:00",
    "campaignId": 49313,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "emailId": "c123456:t456789:user@example.com"
  }
}

Email Send Skip

{
  "email": "user@example.com",
  "eventName": "emailSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 18:56:10 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 721398,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "email": "user@example.com"
  }
}

Email Subscribe

{
  "email": "user@example.com",
  "eventName": "emailSubscribe",
  "dataFields": {
    "createdAt": "2020-03-20 23:12:00 +00:00",
    "signupSource": "UpdateSubscriptionsAPI",
    "emailListIds": [
      27449
    ],
    "messageTypeIds": [],
    "channelIds": [],
    "email": "user@example.com",
    "profileUpdatedAt": "2020-03-20 23:11:58 +00:00"
  }
}

Email Unsubscribe

{
  "email": "user@example.com",
  "eventName": "emailUnSubscribe",
  "dataFields": {
    "campaignId": 1089024,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailId": "c123456:t456789:user@example.com",
    "workflowName": "My test journey",
    "messageTypeIds": [],
    "locale": null,
    "templateId": 1526112,
    "emailSubject": "Upcoming events!",
    "labels": [],
    "unsubSource": "EmailLink",
    "createdAt": "2020-03-20 23:34:15 +00:00",
    "templateName": "My test template",
    "emailListIds": [],
    "messageTypeId": 31082,
    "experimentId": null,
    "channelIds": [
      27447
    ],
    "campaignName": "My test campaign",
    "workflowId": 76786,
    "email": "user@example.com",
    "channelId": 27447
  }
}

Hosted Unsubscribe Click

{
  "email": "user@example.com",
  "userId": "1",
  "eventName": "hostedUnsubscribeClick",
  "dataFields": {
    "country": "United States",
    "city": "San Jose",
    "campaignId": 1074721,
    "ip": "192.168.0.1",
    "userAgentDevice": "Mac",
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailId": "c123456:t456789:user@example.com",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
    "workflowName": "My journey",
    "locale": null,
    "templateId": 1506266,
    "emailSubject": "My email subject",
    "url": "https://iterable.com",
    "labels": [],
    "createdAt": "2020-03-21 00:24:08 +00:00",
    "templateName": "My email template",
    "messageTypeId": 13406,
    "experimentId": null,
    "region": "CA",
    "campaignName": "My email campaign",
    "workflowId": 60102,
    "email": "user@example.com",
    "channelId": 12466
  }
}

In-App Click

{
  "email": "user@example.com",
  "eventName": "inAppClick",
  "dataFields": {
    "email": "user@example.com",
    "createdAt": "2018-03-27 00:44:40 +00:00",
    "campaignId": 269450
  }
}

In-App Open

{
  "email": "user@example.com",
  "eventName": "inAppOpen",
  "dataFields": {
    "email": "user@example.com",
    "createdAt": "2018-03-27 00:44:30 +00:00",
    "campaignId": 269450
  }
}

In-App Send

{
  "email": "user@example.com",
  "eventName": "inAppSend",
  "dataFields": {
    "messageContext": {
      "saveToInbox": false,
      "trigger": "immediate"
    },
    "campaignId": 732678,
    "contentId": 18997,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "workflowName": null,
    "emailId": "c123456:t456789:user@example.com",
    "locale": null,
    "templateId": 1032729,
    "inAppBody": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML",
    "expiresAt": "2019-08-08 22:37:40 +00:00",
    "labels": [],
    "createdAt": "2019-08-07 22:37:40 +00:00",
    "templateName": "My template name",
    "messageTypeId": 14381,
    "experimentId": null,
    "campaignName": "My campaign name",
    "workflowId": null,
    "channelId": 13353,
    "email": "user@example.com"
  }
}

In-App Send Skip

{
  "email": "user@example.com",
  "eventName": "inAppSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 22:42:18 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 732678,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "email": "user@example.com"
  }
}

Push Bounce

{
  "email": "user@example.com",
  "eventName": "pushBounce",
  "dataFields": {
    "platformEndpoint": "<Platform endpoint>",
    "email": "user@example.com",
    "createdAt": "2016-12-10 01:00:38 +00:00",
    "campaignId": 74768,
    "templateId": 113554,
    "pushMessage": "Push message text",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 2203,
    "messageTypeId": 2439,
    "experimentId": null,
    "payload": {
      "path": "yourpath/subpath"
    },
    "sound": "",
    "badge": null,
    "contentAvailable": false,
    "deeplink": null,
    "locale": null
  }
}

Push Open

{
  "email": "user@example.com",
  "eventName": "pushOpen",
  "dataFields": {
    "appAlreadyRunning": false,
    "email": "user@example.com",
    "createdAt": "2016-12-08 01:25:22 +00:00",
    "campaignId": 74768,
    "templateId": 113554,
    "pushMessage": "Push message text",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 2203,
    "messageTypeId": 2439,
    "experimentId": null,
    "payload": {
      "path": "shop_home"
    },
    "sound": null,
    "badge": null,
    "contentAvailable": false,
    "deeplink": null,
    "locale": null
  }
}

Push Send

{
  "email": "user@example.com",
  "eventName": "pushSend",
  "dataFields": {
    "contentId": 6724,
    "platformEndpoint": "<Platform endpoint>",
    "email": "user@example.com",
    "createdAt": "2016-12-08 00:53:11 +00:00",
    "campaignId": 74758,
    "templateId": 113541,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "pushMessage": "Push message text",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 1744,
    "messageTypeId": 1759,
    "experimentId": null,
    "payload": {
      "a": "2"
    },
    "sound": "",
    "badge": "",
    "contentAvailable": false,
    "deeplink": null,
    "locale": null
  }
}

Push Send Skip

{
  "email": "user@example.com",
  "eventName": "pushSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 22:28:51 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 732667,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "email": "user@example.com"
  }
}

Push Uninstall

{
  "email": "user@example.com",
  "eventName": "pushUninstall",
  "dataFields": {
    "isGhostPush": false,
    "platformEndpoint": "<Platform endpoint>",
    "email": "user@example.com",
    "createdAt": "2016-12-09 20:50:54 +00:00",
    "campaignId": 74768,
    "templateId": 113554,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "pushMessage": "Push message text",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 2203,
    "messageTypeId": 2439,
    "experimentId": null,
    "payload": {
      "path": "your_folder/30"
    },
    "sound": "",
    "badge": null,
    "contentAvailable": false,
    "deeplink": null,
    "locale": null
  }
}

SMS Bounce

{
   "email": "user@example.com",
   "eventName": "smsBounce",
   "dataFields": {
      "campaignId": 3333333,
      "campaignName": "Campaign name",
      "workflowId": null,
      "workflowName": null,
      "templateName": "Template name",
      "locale": null,
      "channelId": 11111,
      "messageTypeId": 22222,
      "experimentId": null,
      "labels": [],
      "smsMessage": "Test SMS",
      "fromPhoneNumberId": 2072,
      "imageUrl": null,
      "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
      "messageStatus": "undelivered",
      "toPhoneNumber": "+14155550132",
      "errorCode": "30003",
      "email": "user@example.com",
      "createdAt": "2022-05-18 16:11:20 +00:00",
      "templateId": 5555555,
      "emailId": "c123456:t456789:user@example.com"
   }
}

SMS Click

{
  "email": "user@example.com",
  "eventName": "smsClick",
  "dataFields": {
    "campaignId": 1234567,
    "campaignName": "My test campaign",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template",
    "locale": null,
    "channelId": 98765,
    "messageTypeId": 43210,
    "experimentId": null,
    "labels": [],
    "smsMessage": "Test SMS! https://www.example.com",
    "fromPhoneNumberId": 1234,
    "imageUrl": null,
    "clickedUrl": "https://www.example.com",
    "email": "user@example.com",
    "createdAt": "2022-03-10 05:00:14 +00:00",
    "templateId": 1112222,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailId": "c123456:t9876543:user@example.com"
  }
}

SMS Received

{
  "email": "user@example.com",
  "eventName": "smsReceived",
  "dataFields": {
    "fromPhoneNumber": "+14155550132",
    "toPhoneNumber": "+14155550132",
    "smsMessage": "Message text",
    "email": "user@example.com",
    "createdAt": "2016-12-05 22:51:25 +00:00"
  }
}

SMS Send

{
   "email": "user@example.com",
   "eventName": "smsSend",
   "dataFields": {
      "campaignId": 4413580,
      "campaignName": "Campaign name",
      "workflowId": null,
      "workflowName": null,
      "templateName": "Template name",
      "locale": null,
      "channelId": 99999,
      "messageTypeId": 99999,
      "experimentId": null,
      "labels": [],
      "smsMessage": "SMS message body",
      "fromPhoneNumberId": 1111,
      "imageUrl": null,
      "toPhoneNumber": "+14155550132",
      "fromSMSSenderId": 1111,
      "mmsSendCount": 0,
      "smsSendCount": 1,
      "isSMSEstimation": false,
      "catalogLookupCount": 0,
      "catalogCollectionCount": 0,
      "productRecommendationCount": 0,
      "transactionalData": "{}",
      "email": "user@example.com",
      "createdAt": "2022-05-17 23:07:53 +00:00",
      "templateId": 555555,
      "contentId": 444444,
      "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
      "emailId": "c123456:t9876543:user@example.com"
   }
}

SMS Send Skip

{
  "email": "user@example.com",
  "eventName": "smsSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 18:49:48 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 729390,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "email": "user@example.com"
  }
}

Triggered Send

{
  "email": "user@example.com",
  "eventName": "emailSend",
  "dataFields": {
    "contentId": 274222,
    "email": "user@example.com",
    "createdAt": "2016-12-02 18:51:40 +00:00",
    "campaignId": 49313,
    "transactionalData": {
      "__comment": "transactionalData lists the fields contained in the dataFields property of the API call or event used to trigger the email, campaign, or journey. transactionalData must contain no more than 12k characters in total."
    },
    "templateId": 79190,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "emailId": "c123456:t9876543:user@example.com"
  }
}

Web Push Send

{
  "email": "user@example.com",
  "eventName": "webPushSend",
  "dataFields": {
    "campaignId": 723636,
    "browserToken": "...",
    "contentId": 3681,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "workflowName": "My journey name",
    "emailId": "c123456:t9876543:user@example.com",
    "locale": null,
    "webPushIcon": null,
    "templateId": 1020396,
    "labels": [],
    "createdAt": "2019-08-07 23:43:02 +00:00",
    "templateName": "My template name",
    "webPushMessage": "",
    "messageTypeId": 9106,
    "webPushBody": null,
    "experimentId": null,
    "webPushClickAction": null,
    "campaignName": "My campaign name",
    "workflowId": 53505,
    "channelId": 8539,
    "email": "user@example.com"
  }
}

Web Push Send Skip

{
  "email": "user@example.com",
  "eventName": "webPushSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 23:43:48 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 723636,
    "messageId": "9c438a20d26e4e9f8ad4edea23f811cd",
    "email": "user@example.com"
  }
}

Related articles

Comments

0 comments

Article is closed for comments.