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:
-
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.
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:
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:
- Blast Send
- Email Bounce
- Email Click
- Email Complaint
- Email Open
- Email Send Skip
- Email Subscribe
- Email Unsubscribe
- Hosted Unsubscribe Click
- In-App Click
- In-App Open
- In-App Send
- In-App Send Skip
- Push Bounce
- Push Open
- Push Send
- Push Send Skip
- Push Uninstall
- SMS Bounce
- SMS Click
- SMS Send
- SMS Received
- SMS Send Skip
- Triggered Send
- Web Push Send
- Web Push Send Skip
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" } }
Comments
0 comments
Please sign in to leave a comment.