Journey webhooks send data from Iterable to another app or service when users reach a particular step in a journey.
You can use journey webhooks to:
- Send data to business intelligence tools 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
- Automate phone calls with Twilio
- Update your users' Iterable profiles
- Save data to your own servers
- And more!
Read on to learn how to create webhooks and use them in your journeys.
IMPORTANT
All of the webhooks you set up in Iterable must use HTTPS-based URLs. Starting June 30th, 2022, any of your webhooks that use HTTP will fail. Learn more.
We recently renamed Workflows to Journeys—however, our APIs and field names
still refer to them as "Workflows" (for example, workflowId
).
Table of contents
Creating a journey webhook
To create a journey webhook:
Navigate to Integrations > Journey webhooks.
-
Click New webhook. This will take you to the Create Journey Webhook page:
Give the webhook a name (you'll use this name to select the webhook when you add it to a journey).
For Destination, choose Custom to set up the webhook yourself, or select the preset configuration for Inkit. If you select the Inkit preset webhook, Iterable will automatically select the required fields. (All you have to do is fill them in. 👍)
-
Select the HTTP method that the webhook endpoint requires:
GET
,POST
,PUT
,PATCH
, orDELETE
. (If you're unsure which one to choose, ask the endpoint's owner.)NOTES
- To learn about the different HTTP request methods, check out MDN's HTTP Request Methods support document.
- The only time Iterable saves the data from a server's response to a webhook
call is when the call is a
GET
request made from a User profile tile in a journey. For every other call, the server response is discarded.
-
For Endpoint, enter the destination URL for the HTTP request.
You can use Handlebars expressions to pass user profile fields to the webhook URL. If the values in those expressions will contain anything other than letters, numbers, periods, hyphens, asterisks, or underscores, make sure to surround those parameters with
{{#urlEncode}}
like this:https://api.example.com/update?email={{#urlEncode}}{{email}}{{/urlEncode}}
-
Select an Authentication option:
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 this token 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 OAuth 2.0 client credentials.
With OAuth 2.0 authentication, 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 where Iterable should request the authorization token.
Iterable will fetch an access token from your authorization server by sending a
POST
request to the authorization server URL with the following 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>" }
Iterable will include this access token in a custom header in all subsequent requests, like this:
Authorization: Bearer <ACCESS_TOKEN>
NOTES
- Iterable ignores all response fields except
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, the webhook will use the client ID and secret to fetch a new token, then try the request again. This means that journey webhooks will keep working even after their access tokens expire.
- (Optional) Add Custom headers. Click Add header, then add a Key
and a Value. You can use Handlebars expressions for the value
(for example,
{{myFieldName}}
).
-
Add the webhook request Body (the data that the webhook will send to the app or service you're connecting to the journey).
First, select the type of body to use in the request: JSON or URL-encoded. If you don't know which one to use, ask the endpoint's owner.
Check the Include
email
andworkflowId
option to include those fields in the webhook request.For a JSON body, use the input field to add the JSON data you want to send to the app or service you're connecting to. To include user profile fields in the request body, click Add user field and select a field.
- For a URL-encoded body, click Add form field and enter
name-value pairs. You can use Handlebars expressions in the Value
field. For example, if your Iterable project uses the
firstName
user profile field to store first names, you could enterfirstName
for Name and{{firstName}}
for Value.
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 will use the data from the event or API call in the Handlebars reference.
- If a journey webhook references any fields that aren't on the user’s profile, those fields will be left out of the request (unless they happen to be included in the event or API call that triggers the webhook).
- Different fields can be included in the body of a journey webhook request
depending on the journey's entry source. For example, if your journey uses the
Purchase entry source, a webhook request can include the
total
field (but a List Subscribe entry source can't). Always test a journey webhook before using it in a journey.
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, click 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 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 page.
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.
Using journey webhooks
There are two ways to add webhooks to a journey in Studio:
- The Call webhook tile
- The User profile tile
Adding a webhook in a Call Webhook tile
Use the Call webhook tile to connect apps like Segment, Amplitude, and Inkit to your Iterable journeys, or send data to your own servers.
-
Drag a Call webhook tile onto the canvas.
-
Double-click the tile to open the settings menu.
-
To use one of your existing webhooks, leave the Use a preset journey webhook option switched on, and select one of your webhooks from the dropdown.
Alternatively, switch the Use a preset journey webhook option off, and enter an endpoint URL and authorization token.
This will create a new webhook that sends
POST
requests to the endpoint URL, along with information about the triggering event. Iterable will discard any response it receives from the server.NOTE
Webhooks you create in the Call webhook tile won't save to your Journey Webhooks page and can't be reused in multiple journeys.
Click Update to save the tile.
Save and turn on the journey.
Adding a webhook in a User Profile tile
The User Profile tile lets you update a user's Iterable profile when they reach a certain stage of a journey. You can set up the tile to use a webhook to make these updates.
-
Drag a User Profile tile onto the canvas.
-
Double-click the tile to open the tile settings menu.
-
Select the Retrieve data from a webhook option.
This will create a new webhook that sends
GET
requests to the endpoint URL, appending the user's email address as a URL parameter. Iterable will receive a JSON response to the request and use it to update the user's profile.NOTE
Webhooks you create in the User profile tile won't save to your Journey Webhooks page and can't be reused in multiple journeys.
-
Enter the Endpoint URL where Iterable should make a
GET
request.You can use Handlebars expressions to pass user profile fields to the webhook URL. If the values in those expressions will contain anything other than letters, numbers, periods, hyphens, asterisks, or underscores, make sure to surround those parameters with
{{#urlEncode}}
like this:https://api.example.com/update?fullName={{#urlEncode}}{{fullName}}{{/urlEncode}}
Don't add an
email
parameter—Iterable automatically adds it for you! Here's what the complete request looks like:GET https://example.com/endpoint?email=user%40iterable.com
If necessary, enter an Authorization Token. Iterable will use this token to add an
Authorization
header to the webhook request.Click Update to save the tile.
Save and turn on the journey.
Testing a journey webhook
As you're setting up a journey webhook, it can be useful to check the requests it sends to make sure that everything is working as you expect. However, sometimes it's difficult to access a webhook's data.
Try using a service like Webhook.site or RequestBin to set up a test webhook URL and check its incoming requests.
Troubleshooting errors
When Iterable makes a webhook request, it receives an HTTP response back from the server with a status code. Here's how Iterable handles these status codes:
Error code | Iterable's response |
---|---|
200 OK | User continues to the next step in the journey |
429 Too Many Requests | Retry the webhook every 3 minutes (maximum 3 attempts) |
4XX | User exits the journey |
502 Bad Gateway | Retry the webhook every 3 minutes (maximum 3 attempts) |
503 Service Unavailable | Retry the webhook every 3 minutes (maximum 3 attempts) |
504 Gateway Timeout | Retry the webhook every 3 minutes (maximum 3 attempts) |
All other status codes | User exits the journey |
Other errors:
- If the webhook has an invalid URL or returns an SSL exception, the user will exit the journey.
- For User Profile tiles, 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 3-minute delay (up to 3 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 the client ID and secret) and then try the call again. After a total of 3 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 users.
When there's a problem with one of your journey webhooks, you'll receive a notification in your project notification center.
Example journey webhook requests
Let's say you have a journey called "Welcome Sequence" (journey ID: 12345),
which uses the API call
entry source and contains three journey webhooks. Here
are some sample calls and responses for this journey.
POST
request
Let's say you add a user to the Welcome Sequence journey by calling Iterable's
POST /api/workflows/triggerWorkflow
API endpoint, and you include this data in the request:
{ "workflowId": 12345, "email": "test.user@example.com", "dataFields": { "promotionId": 123, "color": "red" } }
If the journey contains a Call webhook tile that makes a POST
request,
its request body might look like this:
{ "promotionId": 123, "color": "red", "email": "test.user@example.com", "workflowId": 12345 }
PUT
request
Let's say you make a call to the Iterable POST /api/workflows/triggerWorkflow
API endpoint that looks like
this:
{ "workflowId": 12345, "email": "user@example.com", "dataFields": { "promotionId": 123, "color": "red" } }
This call would add the user user@example.com
to the Welcome Sequence journey.
If the journey contains a webhook that includes the user profile fields city
and state
in the JSON request body, Iterable would send the following PUT
request when the user reaches that tile:
{ "city": "San Francisco", "state": "California", "promotionId": 123, "color": "red" }
GET
request
When you configure a User profile tile in a journey to retrieve data from a
webhook, it will make GET
requests to the URL that you specify (appending
email
as a query parameter). For example:
https://api.example.com/webhook/endpoint?email=user@example.com
This endpoint might return JSON data such as:
{ "firstName": "Test", "lastName": "User" }
After receiving this response, Iterable would update user@example.com
to have
a firstName
of Test
and a lastName
of User
.
Questions?
To learn more about building journeys, see the Journeys section of our support docs.
To learn about monitoring events (like message sends or clicks) in your Iterable project, see System Webhooks.
Comments
0 comments
Please sign in to leave a comment.