Webhooks are HTTP requests that send data from Iterable to another server (either your own or a third-party service).
There are two kinds of webhooks in Iterable:
- System webhooks — Triggered each time Iterable tracks specific events (like message sends or link clicks)
- Journey webhooks — Send data to an external server whenever contacts reach a particular step in a journey
Read on to learn more about journey webhooks.
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.
Table of contents
Using journey webhooks
You can use journey webhooks to:
- Send data to a BI tool like Amplitude or Looker
- Save data to Segment
- Set up a direct mail integration with Inkit or Lob
- Launch NPS surveys with Delighted
- Trigger an action on Zapier
- Use Twilio to automate phone calls
- Save data to your own servers
- And more!
Iterable provides four types of journey webhooks:
Basic webhooks - Basic webhooks send
POST
requests to their specified URLs, including information about the triggering event. These webhooks are configured directly in a journey, in a Call Webhook tile. They discard any server response.-
Custom webhooks - Custom webhooks are the most configurable kind of journey webhook. They support various HTTP methods (
GET
,PUT
,POST
,PATCH
, andDELETE
), can use Basic authentication or OAuth 2 (client credentials) authorization, and they can include a custom request body (JSON or form URL-encoded), which you can personalize with user fields. They're configured on the Integrations > Journey Webhooks page, and journeys include them through a Call Webhook tile.When setting up a custom webhook, you can optionally choose a preset configuration for one of Iterable's partners (currently, there's a preset configuration for Inkit).
Update user profile webhooks - These webhooks send a
GET
request to a specified URL, with the user's email address appended as a URL parameter. Iterable uses the response from the webhook server to update the user's Iterable profile.
IMPORTANT
All of the webhooks you set up in Iterable must use HTTPS-based URLs. Starting June 30th, 2022, webhooks that use HTTP URLs will fail. Learn more about this update.
Testing webhooks
As you're setting up a webhook, it's often useful to inspect the requests it sends make sure that everything works as you expect. However, it's sometimes difficult to get access to the webhook's data.
As a workaround, try using a service that allows you to set up a test webhook URL and inspect its incoming requests. For example, try Webhook.site or RequestBin.
Managing your journey webhooks
To view the journey webhooks that have been set up for your Iterable project, navigate to Integrations > Journey Webhooks. On this page, you can create, copy, edit, and delete journey webhooks.
To view the details for a particular journey webhook, twirl down the arrow next to its name. You'll see information about the request body that's included with the webhook, as well as a list of journey tiles that rely on it.
To edit, copy, or delete a journey webhook, choose an option from the menu on the right-hand side of its row.
To delete multiple journey webhooks at once, select them with the checkboxes on the left and click the Delete button that appears at the top of the screen.
TIPS
- A copy of a journey webhook doesn't automatically include the same authentication settings as the original. You'll need to set up authentication manually.
- Before deleting a journey webhook, check to see if it's used in any live journeys. If a user reaches a Call webhook tile that references a deleted journey webhook, they'll exit the journey.
Basic webhooks
To make a POST
request to an external server as part of an Iterable journey,
and include information about the journey's triggering event in the request body,
you can use a basic webhook.
TIP
It's generally best to use a custom webhook instead of a basic webhook. Custom webhooks can perform the same function, and you can reuse them across multiple journeys and journey tiles.
Creating a basic webhook
To set up a basic webhook:
Navigate to Messaging > Journeys.
Open a journey or create a new one.
Drag a Call Webhook tile onto the canvas and attach it to another journey tile.
-
Configure the Call Webhook tile:
Open the tile by double-clicking on it:
Disable Use Pre-Configured Journey Webhook.
-
For Endpoint URL, enter the destination URL for the
POST
request.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.
To pass user profile fields to a webhook URL, use merge parameters. However, if the values associated with those merge parameters may contain anything other than alphanumeric characters, periods, hyphens, asterisks, or underscores, surround those fields with calls to
{{#urlEncode}}
. For example:https://api.example.com/update?email={{#urlEncode}}{{email}}{{/urlEncode}}
If necessary, specify an Authorization Token. This value will be sent as the
Authorization
header in the HTTP request.To save the journey tile, click Update Tile.
To save the journey, click Save.
If necessary, enable the journey.
Example basic webhook
Here's a sample call to Iterable's POST /api/workflows/triggerWorkflow
API endpoint:
{ "workflowId": 12345, "email": "test.user@example.com", "dataFields": { "promotionId": 123, "color": "red" } }
Assume this call triggers journey 12345, which includes a basic webhook that
sends a POST
request to its configured URL. That webhook will include the
following request body:
{ "promotionId": 123, "color": "red", "email": "test.user@example.com", "workflowId": 12345 }
NOTE
The specific fields included in the body of a journey webhook request depend on the
type of trigger tile associated with the journey. For example, a Purchased
journey trigger tile causes a basic webhook request to include a total
field, but
a Subscribed To List journey trigger tile does not. You should always test a
journey webhook before using it in a journey.
Custom webhooks
Custom webhooks are more customizable than basic webhooks. They can:
- Use various HTTP methods:
GET
,PUT
,POST
,PATCH
, andDELETE
. - Include custom request headers.
- Include a custom request body (either JSON or form URL-encoded).
- Use Basic authentication or OAuth 2 (client credentials) authorization.
- Use a preset partner configuration (currently, Iterable provides a preset webhook configuration for Inkit).
Creating a custom webhook
To set up a custom webhook:
Navigate to Integrations > Journey Webhooks.
-
Click New Webhook, which brings up the Create Journey Webhook page:
Give the webhook a Name, which you can use to select the webhook when adding it to a journey.
-
Choose a Destination: Custom to set up all the webhook's details yourself, or the preset configuration for Inkit.
INFO
If you select the Inkit preset, Iterable will automatically configure the journey webhook to include the required fields. Fill them in as needed.
-
Select the HTTP method expected by the webhook's endpoint. If you're unsure which to choose, ask the endpoint's owner.
NOTES
- For an overview of the various HTTP request methods, check out MDN's HTTP request methods document.
- Iterable never uses or saves the data included in the server's response to a custom journey webhook call.
-
For Endpoint, enter the destination URL for the HTTP request.
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.
To pass user profile fields to a webhook URL, use merge parameters. However, if the values associated with those merge parameters may contain anything other than alphanumeric characters, periods, hyphens, asterisks, or underscores, surround those fields with calls to
{{#urlEncode}}
. For example:https://api.example.com/update?email={{#urlEncode}}{{email}}{{/urlEncode}}
-
Select an Authentication scheme:
None - Choose this option if your webhook endpoint does not require authentication.
-
Basic - Choose this option if your webhook endpoint requires Basic authentication.
When you select this option, you'll need to provide an Authentication Token. Iterable will use it to add the following header to your webhook requests:
Authorization: Basic <YOUR_AUTHENTICATION_TOKEN>
NOTE
Iterable does not encode your authentication token. If necessary, you can manually encode it before assigning it to the journey webhook.
-
OAuth 2.0 - Choose this option to authenticate your webhook with an OAuth 2.0 client credentials flow.
With this approach, Iterable uses your client ID and client secret to fetch an access token from your authorization server. To do this, it sends a
POST
request to the authorization server's URL, with a JSON request body:{ "client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>", "grant_type": "client_credentials" }
The webhook expects to receive a JSON response with an
access_token
field:{ "access_token": "<ACCESS_TOKEN>" }
NOTE
Other than
access_token
, Iterable ignores all response fields.Iterable uses this access token in subsequent requests, in a custom header:
Authorization: Bearer <ACCESS_TOKEN>
.Iterable refreshes access tokens at least every 10 days (but sometimes more frequently). If an expired access token causes a
401 Unauthorized
response, its webhook will use the client ID and secret to fetch a new token, and then try the request again. This means that journey webhooks will keep working even after their access tokens expire.With this option, you'll need to provide three additional pieces of information:
Client ID - The client ID that Iterable should use to request an access token from the authorization server.
Client secret - The client secret that Iterable should use to request an access token from the authorization server.
Token URL - The URL from which Iterable should request the authorization token.
- Add Custom Headers, if necessary. To do this, click Add Header. Then,
specify a Key and a Value. To customize the value, use merge parameters
(for example,
{{myFieldName}}
).
-
Define the webhook's request Body. This is the data that it will send to the external server.
First, select the type of body to use in the request: JSON or URL-encoded form. If you don't know which is correct, ask the endpoint's owner.
Check Include
email
andworkflowId
to include those fields in the journey webhook request.For a JSON body, use the text input to specify any JSON data to send to the server. To include user profile fields in the request body, click Add user field and select a field.
- For a Form url-encoded body, click Add form field and enter
name-value pairs. Use merge parameters (Handlebars) in the values as needed.
For example, you might enter a Name of
firstName
and a Value of{{firstName}}
NOTES
- If a journey webhook references a field that is found on both the user's Iterable user profile and in the event or API call that triggers the journey, Iterable uses the data from the event or API call to resolve the Handlebars reference.
- In the request for a journey webhook, Iterable omits fields referenced in the webhook definition but not found on the user's profile (unless they happen to be included on the event or API that triggers the webhook in the first place).
Adding the custom webhook to a journey
To add the custom webhook to an Iterable journey:
Navigate to Messaging > Journeys.
Open a journey or create a new one.
Drag a Call Webhook tile onto the journey canvas and attach it to another journey tile.
-
Configure the Call Webhook tile:
Open the tile by double-clicking it.
Enable Use Pre-Configured Journey Webhook.
In the Select a Webhook drop-down menu, choose the custom webhook created above.
Click Update Tile to save the journey tile.
Click Save to save the journey.
If necessary, enable the journey.
Example custom webhook
Here's a sample call to Iterable's POST /api/workflows/triggerWorkflow
API endpoint:
{ "workflowId": 12345, "email": "user@example.com", "dataFields": { "promotionId": 123, "color": "red" } }
This call trigger journey 12345 for user user@example.com
. Assume that journey
12345 includes a custom journey webhook that:
- Makes a
PUT
call tohttps://api.example.com/webhook/endpoint
- Includes custom header
Authorization: 123456789
- Includes user profile fields
city
andstate
in the JSON request body
As a result, Iterable will send this webhook request:
HTTP method:
PUT
URL:
https://api.example.com/webhook/endpoint
Custom HTTP headers:
Authorization: 123456789
-
Request body:
{ "city": "San Francisco", "state": "California", "promotionId": 123, "color": "red" }
Update user profile webhooks
To use the response from a journey webhook to update a user's Iterable profile, use an update user profile webhook. These webhooks:
- Make
GET
requests to a specified URL, appending the user's email address as a URL parameter. - Use the JSON response coming back from the request to update the user's Iterable profile.
Adding an update user profile webhook to an Iterable journey
To add an update user profile webhook to an Iterable journey:
Navigate to Messaging > Journeys.
Open a journey or create a new one.
Drag an Update User Profile Webhook tile onto the journey canvas and attach it to another journey tile.
-
Configure the Update User Profile Webhook tile:
-
Open the tile by double-clicking it.
-
For Endpoint URL, specify the webhook URL to which Iterable should make a
GET
request.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.
-
To pass user profile fields to a webhook URL, use merge parameters. However, if the values surfaced by those merge parameters may contain anything other than alphanumeric characters, periods, hyphens, asterisks, or underscores, surround those fields with calls to
{{#urlEncode}}
. For example:https://api.example.com/update?fullName={{#urlEncode}}{{fullName}}{{/urlEncode}}
Do not include an
email
parameter, since Iterable will automatically append it to the URL for this type of webhook.
-
If necessary, specify an Authorization Token. This will be used for an
Authorization
header in the webhook's request.Click Update Tile to save the journey tile.
-
Click Save to save the journey.
If necessary, enable the journey.
Example update user profile webhook response
For an update user profile journey webhook request sent to
https://api.example.com/webhook/endpoint?email=docs@iterable.com
, imagine
that the server responds with this JSON data:
{ "firstName": "Test", "lastName": "User" }
Based on this response body, Iterable would update docs@iterable.com
to have a
firstName
of Test
and a lastName
of User
.
Errors
When Iterable makes a webhook request, it receives an HTTP response back from the server, including a status code. Iterable handles these status codes as follows:
Error code | Iterable's response |
---|---|
200 OK | Continue to next step in the journey |
429 Too Many requests | Retry the webhook every three minutes, stopping after three attempts |
4XX | User exits the journey |
502 Bad Gateway | Retry the webhook every three minutes, stopping after three attempts |
503 Service Unavailable | Retry the webhook every three minutes, stopping after three attempts |
504 Gateway Timeout | Retry the webhook every three minutes, stopping after three attempts |
Other status codes | User exits the journey |
Other errors:
- If the webhook has an invalid URL or yields an SSL exception, the user will exit the journey.
- For update user profile webhooks, if the response body is not a valid JSON object, the user will exit the journey.
- If a webhook call times out after 10 seconds, returns a non-
200
HTTP code, or doesn't return valid JSON, Iterable will retry the call after a three minute delay (up to three times). - If a journey webhook that uses OAuth 2.0 receives a
401 Unauthorized
response for one of its calls, it will fetch a new access token (using its client ID and secret) and then try the call again. After a total of three failures (for either call: the access token refresh call, or the webhook call itself), the user will exit the journey. However, the journey will continue to try those calls for future contacts.
Journey webhook errors cause notifications to display in your Iterable project's notification center.
Questions?
To learn more about building journeys, see the Journeys section of our support docs.
Comments
0 comments
Please sign in to leave a comment.