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

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

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 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 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 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 a 401 before its expiration (based on expires_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>

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.

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

  

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