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
We've renamed Workflows to Journeys. However, our APIs and field names still
refer to them as "Workflows" (for example, workflowId
).
In this article
Creating journey webhooks
To create a journey webhook:
Navigate to Integrations > Journey webhooks.
-
Click New webhook. This takes 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 automatically selects 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 can 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 or if you are using a custom authentication method.
-
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 uses 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.
To fetch an access token from your authorization server, Iterable sends a
POST
request to the authorization server URL. This request has:A
content-type
header set toapplication/x-www-form-urlencoded
.-
A form-encoded body with this data:
client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=client_credentials
The webhook expects to receive a JSON response with these fields:
access_token
- A string that represents the access token to use in subsequent requests from Iterable to the webhook endpoint.-
expires_in
- Optional. An integer that represents the number of seconds after being fetched by Iterable that theaccess_token
expires on your servers.This value does not affect how long Iterable caches the
access_token
(up to 10 days).If Iterable receives a
401
response for an OAuth 2.0-authorized webhook request, it uses the client ID and secret to fetch a new token and attempts the request again. This retry process can happen up to three times.If an
access_token
causes a401
before its expiration (based onexpires_in
), Iterable adds a notification to your project's Notification Center.
For example, this response returns an access token that expires in 5 days (432000 seconds):
{ "access_token": "<ACCESS_TOKEN>", "expires_in": 432000 }
After receiving an access token for the webhook, Iterable includes it as a custom header in future requests:
Authorization: Bearer <ACCESS_TOKEN>
- (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}}
).
If you're authenticating with an API key, you can add a custom header to your webhook request to include that secret. For example, you could add a header with the key X-Api-Key
. The value of this header would be the secret you want to include in the request.
NOTE
There are multiple ways to include API keys in a webhook request. Always check with the service you are sending the webhook to for the correct way to include an API key in the request headers.
For security, Iterable does not accept API keys in the URL of a webhook request.
-
Add the webhook request Body (the data that the webhook should 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 uses the data from the event or API call in the Handlebars reference.
- If a journey webhook references any fields that aren't on a user’s profile, those fields are left out of the webhook 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 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.
- When you change an existing journey webhook, the changes take some time to propagate due to caching. For example, if you change the URL, Iterable may continue to send data to the old webhook URL for a short time after you update it.
Testing journey webhooks
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 exits the journey.
For User Profile tiles, if the response body is not a valid JSON object, the user exits the journey.
If a webhook call times out after 10 seconds, returns a non-
200
HTTP code, or doesn't return valid JSON, Iterable retries the call after a 3-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, Iterable uses the client ID and secret to fetch a new access token. Then, it tries the webhook request again.If the original call and three retries all fail, the user exits the journey. However, the journey attempts those webhook requests for future users as needed.
If a webhook's request to fetch an OAuth 2.0 access token fails, the user exits the journey.
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,
that request includes the items contained in the dataFields
of the triggering
API call, 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 makes 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
.
Learn more
To learn more about using webhooks in journeys, see Setting Up Integrations in a Journey.
To learn about monitoring events (like message sends or clicks) in your Iterable project, see System Webhooks.