When system webhooks are enabled, Iterable sends information about events such as email sends, email opens, push notifications, and others to third-party systems.
Iterable calls a system webhook any time its associated events occurs in an Iterable project—they do not watch for events in a specific template, campaign, or workflow.
NOTE
To call a webhook as part of a specific workflow, use a workflow 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.
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 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)", "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 workflow", "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 workflow", "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": { "smsProviderResponse": { "status": 404, "message": "The requested resource /2010-04-01/Accounts/ACCOUNT_NUMBER/Messages.json was not found", "code": 20404, "more_info": "https://www.twilio.com/docs/errors/20404" }, "email": "docs@iterable.com", "createdAt": "2016-12-05 22:43:24 +00:00", "campaignId": 74003, "templateId": 112561, "smsMessage": "Here is example message, please respond with 'received'", "campaignName": "My campaign name", "workflowId": null, "workflowName": null, "templateName": "My template name", "channelId": 4270, "messageTypeId": 4769, "experimentId": null, "fromPhoneNumberId": 268, "imageUrl": null, "locale": null, "emailId": "c74003:t112561: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": { "toPhoneNumber": "+16503926753", "fromSMSSenderId": 258, "contentId": 2086, "email": "docs@iterable.com", "createdAt": "2016-12-05 21:50:32 +00:00", "campaignId": 73974, "templateId": 112523, "smsMessage": "Message text", "campaignName": "My campaign name", "workflowId": null, "workflowName": null, "templateName": "My template name", "channelId": 4270, "messageTypeId": 4769, "experimentId": null, "fromPhoneNumberId": 258, "imageUrl": null, "locale": null, "emailId": "c73974:t112523: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 workflow. 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 workflow 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.