Journey Webhooks

Webhooks are HTTP requests that send data from Iterable to another server (either your own or a third-party service).

There are two kinds of webhooks in Iterable:

• System webhooks — Triggered each time Iterable tracks specific events (like message sends or link clicks)
• Journey webhooks — Send data to an external server whenever contacts reach a particular step in a journey

Read on to learn more about journey webhooks.

# Table of contents

# Using journey webhooks

You can use journey webhooks to:

• Send data to a BI tool 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
• Use Twilio to automate phone calls
• Save data to your own servers
• And more!

Iterable provides four types of journey webhooks:

• Basic webhooks - Basic webhooks send POST requests to their specified URLs, including information about the triggering event. These webhooks are configured directly in a journey, in a Call Webhook tile. They discard any server response.

• Custom webhooks - Custom webhooks are the most configurable kind of journey webhook. They support various HTTP methods (GET, PUT, POST, PATCH, and DELETE), can use Basic authentication or OAuth 2 (client credentials) authorization, and they can include a custom request body (JSON or form URL-encoded), which you can personalize with user fields. They're configured on the Integrations > Journey Webhooks page, and journeys include them through a Call Webhook tile.

  When setting up a custom webhook, you can optionally choose a preset configuration for one of Iterable's partners (currently, there's a preset configuration for Inkit).

• Update user profile webhooks - These webhooks send a GET request to a specified URL, with the user's email address appended as a URL parameter. Iterable uses the response from the webhook server to update the user's Iterable profile.

# Testing webhooks

As you're setting up a webhook, it's often useful to inspect the requests it sends make sure that everything works as you expect. However, it's sometimes difficult to get access to the webhook's data.

As a workaround, try using a service that allows you to set up a test webhook URL and inspect its incoming requests. For example, try Webhook.site or RequestBin.

# 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, twirl down 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-hand 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 screen.

# Basic webhooks

To make a POST request to an external server as part of an Iterable journey, and include information about the journey's triggering event in the request body, you can use a basic webhook.

# Creating a basic webhook

To set up a basic webhook:

1. Navigate to Messaging > Journeys.

2. Open a journey or create a new one.

3. Drag a Call Webhook tile onto the canvas and attach it to another journey tile.

4. Configure the Call Webhook tile:

   • Open the tile by double-clicking on it:

   • Disable Use Pre-Configured Journey Webhook.

   • For Endpoint URL, enter the destination URL for the POST request.

     IMPORTANT

     All webhooks defined in Iterable must use HTTPS-based URLs. Starting June 30th, 2022, webhooks that rely on HTTP URLs will fail. For more information, read these release notes.

     To pass user profile fields to a webhook URL, use merge parameters. However, if the values associated with those merge parameters may contain anything other than alphanumeric characters, periods, hyphens, asterisks, or underscores, surround those fields with calls to {{#urlEncode}}. For example:

     https://api.example.com/update?email={{#urlEncode}}{{email}}{{/urlEncode}}
     

   • If necessary, specify an Authorization Token. This value will be sent as the Authorization header in the HTTP request.

   • To save the journey tile, click Update Tile.

5. To save the journey, click Save.

6. If necessary, enable the journey.

# Example basic webhook

Here's a sample call to Iterable's POST /api/workflows/triggerWorkflow API endpoint:

{
    "workflowId": 12345,
    "email": "test.user@example.com",
    "dataFields": {
        "promotionId": 123,
        "color": "red"
    }
}

Assume this call triggers journey 12345, which includes a basic webhook that sends a POST request to its configured URL. That webhook will include the following request body:

{
    "promotionId": 123,
    "color": "red",
    "email": "test.user@example.com",
    "workflowId": 12345
}

# Custom webhooks

Custom webhooks are more customizable than basic webhooks. They can:

• Use various HTTP methods: GET, PUT, POST, PATCH, and DELETE.
• Include custom request headers.
• Include a custom request body (either JSON or form URL-encoded).
• Use Basic authentication or OAuth 2 (client credentials) authorization.
• Use a preset partner configuration (currently, Iterable provides a preset webhook configuration for Inkit).

# Creating a custom webhook

To set up a custom webhook:

1. Navigate to Integrations > Journey Webhooks.

2. Click New Webhook, which brings up the Create Journey Webhook page:

   

3. Give the webhook a Name, which you can use to select the webhook when adding it to a journey.

4. Choose a Destination: Custom to set up all the webhook's details yourself, or the preset configuration for Inkit.

   INFO

   If you select the Inkit preset, Iterable will automatically configure the journey webhook to include the required fields. Fill them in as needed.

5. Select the HTTP method expected by the webhook's endpoint. If you're unsure which to choose, ask the endpoint's owner.

   NOTES

   • For an overview of the various HTTP request methods, check out MDN's HTTP request methods document.
   • Iterable never uses or saves the data included in the server's response to a custom journey webhook call.

6. For Endpoint, enter the destination URL for the HTTP request.

   IMPORTANT

   All webhooks defined in Iterable must use HTTPS-based URLs. Starting June 30th, 2022, webhooks that rely on HTTP URLs will fail. For more information, read these release notes.

   To pass user profile fields to a webhook URL, use merge parameters. However, if the values associated with those merge parameters may contain anything other than alphanumeric characters, periods, hyphens, asterisks, or underscores, surround those fields with calls to {{#urlEncode}}. For example:

   https://api.example.com/update?email={{#urlEncode}}{{email}}{{/urlEncode}}
   

7. Select an Authentication scheme:

   • 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 it 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 an OAuth 2.0 client credentials flow.

     With this approach, Iterable uses your client ID and client secret to fetch an access token from your authorization server. To do this, it sends a POST request to the authorization server's URL, with a 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>"
     }
     

     NOTE

     Other than access_token, Iterable ignores all response fields.

     Iterable uses this access token in subsequent requests, in a custom header: Authorization: Bearer <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, its webhook will use the client ID and secret to fetch a new token, and then try the request again. This means that journey webhooks will keep working even after their access tokens expire.

     With this option, 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 from which Iterable should request the authorization token.

9. Define the webhook's request Body. This is the data that it will send to the external server.

   • First, select the type of body to use in the request: JSON or URL-encoded form. If you don't know which is correct, ask the endpoint's owner.

   • Check Include email and workflowId to include those fields in the journey webhook request.

   • For a JSON body, use the text input to specify any JSON data to send to the server. To include user profile fields in the request body, click Add user field and select a field.

   • For a Form url-encoded body, click Add form field and enter name-value pairs. Use merge parameters (Handlebars) in the values as needed. For example, you might enter a Name of firstName and a Value of {{firstName}}

# Adding the custom webhook to a journey

To add the custom webhook to an Iterable journey:

1. Navigate to Messaging > Journeys.

2. Open a journey or create a new one.

3. Drag a Call Webhook tile onto the journey canvas and attach it to another journey tile.

4. Configure the Call Webhook tile:

   • Open the tile by double-clicking it.

   • Enable Use Pre-Configured Journey Webhook.

   • In the Select a Webhook drop-down menu, choose the custom webhook created above.

   • Click Update Tile to save the journey tile.

5. Click Save to save the journey.

6. If necessary, enable the journey.

# Example custom webhook

Here's a sample call to Iterable's POST /api/workflows/triggerWorkflow API endpoint:

{
    "workflowId": 12345,
    "email": "user@example.com",
    "dataFields": {
        "promotionId": 123,
        "color": "red"
    }
}

This call trigger journey 12345 for user user@example.com. Assume that journey 12345 includes a custom journey webhook that:

• Makes a PUT call to https://api.example.com/webhook/endpoint
• Includes custom header Authorization: 123456789
• Includes user profile fields city and state in the JSON request body

As a result, Iterable will send this webhook request:

• HTTP method: PUT

• URL: https://api.example.com/webhook/endpoint

• Custom HTTP headers: Authorization: 123456789

• Request body:

  {
      "city": "San Francisco",
      "state": "California",
      "promotionId": 123,
      "color": "red"
  }
  

# Update user profile webhooks

To use the response from a journey webhook to update a user's Iterable profile, use an update user profile webhook. These webhooks:

• Make GET requests to a specified URL, appending the user's email address as a URL parameter.
• Use the JSON response coming back from the request to update the user's Iterable profile.

# Adding an update user profile webhook to an Iterable journey

To add an update user profile webhook to an Iterable journey:

1. Navigate to Messaging > Journeys.

2. Open a journey or create a new one.

3. Drag an Update User Profile Webhook tile onto the journey canvas and attach it to another journey tile.

4. Configure the Update User Profile Webhook tile:

   • Open the tile by double-clicking it.

     

   • For Endpoint URL, specify the webhook URL to which Iterable should make a GET request.

     IMPORTANT

     All webhooks defined in Iterable must use HTTPS-based URLs. Starting June 30th, 2022, webhooks that rely on HTTP URLs will fail. For more information, read these release notes.

     • To pass user profile fields to a webhook URL, use merge parameters. However, if the values surfaced by those merge parameters may contain anything other than alphanumeric characters, periods, hyphens, asterisks, or underscores, surround those fields with calls to {{#urlEncode}}. For example:

       https://api.example.com/update?fullName={{#urlEncode}}{{fullName}}{{/urlEncode}}
       

       Do not include an email parameter, since Iterable will automatically append it to the URL for this type of webhook.

   • If necessary, specify an Authorization Token. This will be used for an Authorization header in the webhook's request.

   • Click Update Tile to save the journey tile.

5. Click Save to save the journey.

6. If necessary, enable the journey.

# Example update user profile webhook response

For an update user profile journey webhook request sent to https://api.example.com/webhook/endpoint?email=docs@iterable.com, imagine that the server responds with this JSON data:

{
    "firstName": "Test",
    "lastName": "User"
}

Based on this response body, Iterable would update docs@iterable.com to have a firstName of Test and a lastName of User.

# Errors

When Iterable makes a webhook request, it receives an HTTP response back from the server, including a status code. Iterable handles these status codes as follows:

Other errors:

• If the webhook has an invalid URL or yields an SSL exception, the user will exit the journey.
• For update user profile webhooks, 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 three 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, it will fetch a new access token (using its client ID and secret) and then try the call again. After a total of three 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 contacts.

Journey webhook errors cause notifications to display in your Iterable project's notification center.

# Questions?

To learn more about building journeys, see the Journeys section of our support docs.