Journey Webhooks

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.

# Table of contents

# Creating a journey webhook

To create a journey webhook:

1. Navigate to Integrations > Journey webhooks.

2. Click New webhook. This will take you to the Create Journey Webhook page:

   

3. Give the webhook a name (you'll use this name to select the webhook when you add it to a journey).

4. 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. 👍)

5. Select the HTTP method that the webhook endpoint requires: GET, POST, PUT, PATCH, or DELETE. (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.

6. 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}}
   

7. 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.

9. 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 and workflowId 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 enter firstName for Name and {{firstName}} for Value.

# 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.

  

# 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.

1. Drag a Call webhook tile onto the canvas.

   

2. Double-click the tile to open the settings menu.

   

3. 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.

4. Click Update to save the tile.

5. 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.

1. Drag a User Profile tile onto the canvas.

   

2. Double-click the tile to open the tile settings menu.

   

3. 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.

4. 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
   

5. If necessary, enter an Authorization Token. Iterable will use this token to add an Authorization header to the webhook request.

6. Click Update to save the tile.

7. 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:

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.