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/E5V26K38?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 J1qK1c18UUGJFAzz9xnH56584l4 yields the following authorization header:

      Authorization: J1qK1c18UUGJFAzz9xnH56584l4

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

      Authorization: OAuth2 J1qK1c18UUGJFAzz9xnH56584l4

    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

If the initial system webhook call fails because of an error or a one second timeout, Iterable retries the request one time after three minutes.

Webhook examples

Below, find example webhook requests for various event types:

NOTE

There is not yet a system webhook for SMS click events, but this is coming soon, as a follow-on to SMS link shortening and click tracking.

Blast Send

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

Email Bounce

{
  "email": "invalid_email@iterable.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": "invalid_email@iterable.com",
    "createdAt": "2017-05-15 23:59:47 +00:00",
    "campaignId": 114746,
    "messageId": "d0aa7801f91f4824997a631f3ed583c3",
    "emailId": "c114746:t167484:invalid_email@iterable.com"
  }
}

Email Click

{
  "email": "docs@iterable.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": "docs@iterable.com",
    "createdAt": "2016-12-02 20:31:39 +00:00",
    "campaignId": 59667,
    "messageId": "d0aa7801f91f4824997a631f3ed583c3",
    "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": "c59667:t93849:docs@iterable.com"
  }
}

Email Complaint

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

Email Open

{
  "email": "docs@iterable.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": "docs@iterable.com",
    "createdAt": "2016-12-02 18:51:45 +00:00",
    "campaignId": 49313,
    "messageId": "210badf49fe54f2591d64ad0d055f4fb",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "emailId": "c49313:t79190:docs@iterable.com"
  }
}

Email Send Skip

{
  "email": "docs@iterable.com",
  "eventName": "emailSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 18:56:10 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 721398,
    "messageId": "98430abe1b9842c991ce221010121553",
    "email": "docs@iterable.com"
  }
}

Email Subscribe

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

Email Unsubscribe

{
  "email": "docs@iterable.com",
  "eventName": "emailUnSubscribe",
  "dataFields": {
    "campaignId": 1089024,
    "messageId": "bf008db8ab194b65816398c05bf30f99",
    "emailId": "c1089024:t1526112:docs@iterable.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": "docs@iterable.com",
    "channelId": 27447
  }
}

Hosted Unsubscribe Click

{
  "email": "docs@iterable.com",
  "userId": "1",
  "eventName": "hostedUnsubscribeClick",
  "dataFields": {
    "country": "United States",
    "city": "San Jose",
    "campaignId": 1074721,
    "ip": "192.168.0.1",
    "userAgentDevice": "Mac",
    "messageId": "ceb3d4d929fc406ca93b28a0ef1efff1",
    "emailId": "c1074721:t1506266:docs@iterable.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": "docs@iterable.com",
    "channelId": 12466
  }
}

In-App Click

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

In-App Open

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

In-App Send

{
  "email": "docs@iterable.com",
  "eventName": "inAppSend",
  "dataFields": {
    "messageContext": {
      "saveToInbox": false,
      "trigger": "immediate"
    },
    "campaignId": 732678,
    "contentId": 18997,
    "messageId": "vA16d48VVi4LQ5hMuZuquKzL0BXTdQJJUMJRjKnL1",
    "workflowName": null,
    "emailId": "c732678:t1032729:docs@iterable.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": "docs@iterable.com"
  }
}

In-App Send Skip

{
  "email": "docs@iterable.com",
  "eventName": "inAppSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 22:42:18 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 732678,
    "messageId": "705b030b5c514cedad86e76977ea4960",
    "email": "docs@iterable.com"
  }
}

Push Bounce

{
  "email": "docs@iterable.com",
  "eventName": "pushBounce",
  "dataFields": {
    "platformEndpoint": "<Platform endpoint>",
    "email": "docs@iterable.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": "docs@iterable.com",
  "eventName": "pushOpen",
  "dataFields": {
    "appAlreadyRunning": false,
    "email": "docs@iterable.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": "docs@iterable.com",
  "eventName": "pushSend",
  "dataFields": {
    "contentId": 6724,
    "platformEndpoint": "<Platform endpoint>",
    "email": "docs@iterable.com",
    "createdAt": "2016-12-08 00:53:11 +00:00",
    "campaignId": 74758,
    "templateId": 113541,
    "messageId": "73f2d3f13cd04db0b56c6143b179adc5",
    "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": "docs@iterable.com",
  "eventName": "pushSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 22:28:51 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 732667,
    "messageId": "8306ae0c74324635b7554947c5ec0e56",
    "email": "docs@iterable.com"
  }
}

Push Uninstall

{
  "email": "docs@iterable.com",
  "eventName": "pushUninstall",
  "dataFields": {
    "isGhostPush": false,
    "platformEndpoint": "<Platform endpoint>",
    "email": "docs@iterable.com",
    "createdAt": "2016-12-09 20:50:54 +00:00",
    "campaignId": 74768,
    "templateId": 113554,
    "messageId": "73f2d3f13cd04db0b56c6143b179adc5",
    "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":"docs@iterable.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":"466e2704d456425ffb6e5ebd9de1a02a4",
      "messageStatus":"undelivered",
      "toPhoneNumber":"+15005550001",
      "errorCode":"30003",
      "email":"docs@iterable.com",
      "createdAt":"2022-05-18 16:11:20 +00:00",
      "templateId":5555555,
      "emailId":"c1111111:t2222222:docs@iterable.com"
   }
}

SMS Click

{
  "email": "docs@iterable.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": "docs@iterable.com",
    "createdAt": "2022-03-10 05:00:14 +00:00",
    "templateId": 1112222,
    "messageId": "ebd8f3cfc1f74353b423c5e0f3dd8b39",
    "emailId": "c1234567:t9876543:docs@iterable.com"
  }
}

SMS Received

{
  "email": "docs@iterable.com",
  "eventName": "smsReceived",
  "dataFields": {
    "fromPhoneNumber": "+16503926753",
    "toPhoneNumber": "+14155824541",
    "smsMessage": "Message text",
    "email": "docs@iterable.com",
    "createdAt": "2016-12-05 22:51:25 +00:00"
  }
}

SMS Send

{
   "email":"docs@iterable.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":"+15551234567",
      "fromSMSSenderId":1111,
      "mmsSendCount":0,
      "smsSendCount":1,
      "isSMSEstimation":false,
      "catalogLookupCount":0,
      "catalogCollectionCount":0,
      "productRecommendationCount":0,
      "transactionalData":"{}",
      "email":"docs@iterable.com",
      "createdAt":"2022-05-17 23:07:53 +00:00",
      "templateId":555555,
      "contentId":444444,
      "messageId":"adb897b7f81f4153example500520ea",
      "emailId":"a1111111:b2222222:docs@iterable.com"
   }
}

SMS Send Skip

{
  "email": "docs@iterable.com",
  "eventName": "smsSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 18:49:48 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 729390,
    "messageId": "2c780bf42f26485db0fc6571d2e0f6a0",
    "email": "docs@iterable.com"
  }
}

Triggered Send

{
  "email": "docs@iterable.com",
  "eventName": "emailSend",
  "dataFields": {
    "contentId": 274222,
    "email": "docs@iterable.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": "210badf49fe54f2591d64ad0d055f4fb",
    "emailSubject": "My subject",
    "campaignName": "My campaign name",
    "workflowId": null,
    "workflowName": null,
    "templateName": "My template name",
    "channelId": 3420,
    "messageTypeId": 3866,
    "experimentId": null,
    "emailId": "c49313:t79190:docs@iterable.com"
  }
}

Web Push Send

{
  "email": "docs@iterable.com",
  "eventName": "webPushSend",
  "dataFields": {
    "campaignId": 723636,
    "browserToken": "cZn_inqLGPk:APA91bHsn5jo0-4V55RB38eCeLHj8ZXVJYciU7k6Kipbit3lrRlEe2Dt6bNzR4lSf6r2YNVdWY8l90hV0jmb_Y7y5ufcJ68xNI7wbsH6Q2jbEghA_Qo4kWbtu6A4NZN4gxc1xsEbyh7b",
    "contentId": 3681,
    "messageId": "af4c726ae76b48c7871b6d0d7760d47c",
    "workflowName": "My journey name",
    "emailId": "c723636:t1020396:docs@iterable.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": "docs@iterable.com"
  }
}

Web Push Send Skip

{
  "email": "docs@iterable.com",
  "eventName": "webPushSendSkip",
  "dataFields": {
    "createdAt": "2019-08-07 23:43:48 +00:00",
    "reason": "DuplicateMarketingMessage",
    "campaignId": 723636,
    "messageId": "4238c918b20a41dfbe9a910275b76f12",
    "email": "docs@iterable.com"
  }
}

Related articles

Comments

0 comments

Please sign in to leave a comment.