Journey Webhooks

Journey webhooks are secure connections that enable you to send and fetch data from an external app or service when users reach a particular step in a journey. You can use journey webhooks to:

• Fetch live data (beta) from external sources for real-time decisioning and personalization in journeys
• 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!

Once you've configured a journey webhook, you can use an integration tile to call it when users reach that step of a journey, triggering an automatic update.

Read on to learn how to create webhooks and use them in your journeys.

# In this article

# Creating journey webhooks

To create a journey webhook:

1. Navigate to Integrations > Journey webhooks.

2. Click New webhook. This takes 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 automatically selects 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.)

   NOTE

   To learn about the different HTTP request methods, check out MDN's support article HTTP Request Methods.

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

   NOTE

   You can also define variables for a journey webhook's endpoint URL at the tile level in a journey when you configure integration tiles. When you add variables in the journey webhook configuration, the same variables apply to all journey tiles that reference the webhook. Configuring these variables at the tile level allows you to reuse one webhook across multiple tiles and populate dynamic data in each journey tile. Before defining variables, consider your use case and whether you prefer the one-time setup of defining variables at the webhook level or need the flexibility of defining variables on a per-tile basis.

7. 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 to application/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.

     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>

8. (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}}).

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

   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.

10. (Optional, for Live Data beta only) Check the Data Retrieval box to define specific fields from the webhook's payload to make available as live data in journeys (required for journey webhooks that will be referenced in Live Data tiles) (beta). In this section, you need to run a successful test of your journey webhook configuration to fetch a response, then select which fields from the response you wish to make available for referencing as live data.

    Under Test Connection, enter sample JSON data to populate any dynamic parameters included in the endpoint URL. For example, for an endpoint that contains {{email}}:

      {
      "email" = "janine.teagues@example.com"
      }
    

    Click Run Test to test the connection to the external app. Iterable populates the URL with your sample data and makes a call to the endpoint with the method and request body configured above. If the test is successful, Iterable shows the response and generates a list of returned objects and fields available to be defined as live data fields in journeys. The webhook cannot be saved until a successful test is completed—this ensures that broken or mistyped configurations never reach your production journeys.

    In the Live Data Fields section, select up to 10 fields and associated data types from the JSON response that you wish to save as live data fields that can be referenced in journeys. To learn more about configuring and using live data in journeys, see Journey Live Data Overview.

    Beta Feature

    The Data Retrieval option is currently available as part of the Journey Live Data beta for select Iterable customers. If you're interested in using this feature while it's in beta, talk to your customer success manager to request access.

# Managing journey webhooks

To view the journey webhooks that have been set up for your Iterable project, navigate to Integrations > Journey Webhooks. From this page, you can create, copy, edit, and delete journey webhooks.

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

# Copying journey webhooks

To make a copy of an existing journey webhook, click the overflow menu (three dots) for your desired webhook, and select Duplicate Webhook.

# Editing journey webhooks

To edit an existing journey webhook, click the overflow menu (three dots) for your desired webhook, and select Edit Webhook.

When you edit 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.

# Deleting journey webhooks

To delete a journey webhook, click the overflow menu (three dots) for your desired webhook, and click Delete Webhook.

Before deleting a journey webhook, check whether any live journeys currently reference it. If a user reaches a Webhook or Live Data tile that references a deleted journey webhook, they'll exit the journey.

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

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, review your webhook endpoint logs and recent HTTP responses to troubleshoot.

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

# Want to learn more?

For more information about some of the topics in this article, check out these resources:

Support docs

• Integration Tiles
• System Webhooks
• Journey Live Data Overview