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/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.
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
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 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": "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" } }
Comments
0 comments
Article is closed for comments.