Workflow Webhooks

Webhooks are HTTP requests that send data from Iterable to another server, whether your own or third-party. Iterable supports two kinds of webhooks:

• System webhooks, which are triggered each time Iterable tracks specific events of your choosing: email sends, email link clicks, etc.
• Workflow webhooks, which send data to an external server whenever contacts reach a particular workflow step.

This document describes workflow webhooks.

# Table of contents

# Overview of workflow webhooks

Workflow webhooks can be used in many ways. For example:

• Sending data to a BI tool such as Amplitude or Looker.
• Saving data to a tool such as Segment.
• Setting up a direct mail integration with Inkit or Lob.
• Initiating NPS surveys with Delighted.
• Triggering an action on Zapier.
• Using Twilio to automate phone calls.
• Capturing data to your own servers.

Iterable provides four types of workflow 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 workflow, in a Call Webhook node. They discard any server response.

• Custom webhooks - Custom webhooks are the most configurable kind of workflow 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 field. They're configured on the Integrations > Workflow Webhooks page, and workflows include them through a Call Webhook node.

  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 contact'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 workflow webhooks

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

• To view the details for a particular workflow 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 workflow nodes that rely on it:

• To edit, copy, or delete the workflow webhook, choose an option from the menu on the right-hand side of its table row:

• To delete multiple workflow webhooks at a time, 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 worklow, and include information about the workflow'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 > Workflows.

2. Open a workflow or create a new one.

3. Drag a Call Webhook node onto the workflow design surface and attach it to another workflow node.

   

4. Configure the Call Webhook node:

   • Open the node by double-clicking on it:

     

   • Disable Use Pre-Configured Workflow Webhook.

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

     TIPS

     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 workflow node, click Update Node.

5. To save the workflow, click Save.

6. If necessary, enable the workflow.

# 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 workflow 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 > Workflow Webhooks.

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

   

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

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 workflow 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 workflow webhook call.

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

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

To add the custom webhook to an Iterable workflow:

1. Navigate to Messaging > Workflows.

2. Open a workflow or create a new one.

3. Drag a Call Webhook node onto the workflow design surface and attach it to another workflow node.

   

4. Configure the Call Webhook node:

   • Open the node by double-clicking it.

     

   • Enable Use Pre-Configured Workflow Webhook.

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

   • Click Update Node to save the workflow node.

5. Click Save to save the workflow.

6. If necessary, enable the workflow.

# 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 workflow 12345 for user user@example.com. Assume that workflow 12345 includes a custom workflow 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 workflow webhook to update a contact'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 workflow

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

1. Navigate to Messaging > Workflows.

2. Open a workflow or create a new one.

3. Drag an Update User Profile Webhook node onto the workflow design surface and attach it to another workflow node.

   

4. Configure the Update User Profile Webhook node:

   • Open the node by double-clicking it.

     

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

     TIPS

     • 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 Node to save the workflow node.

5. Click Save to save the workflow.

6. If necessary, enable the workflow.

# Example update user profile webhook response

For an update user profile workflow 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 contact will exit the workflow.
• For update user profile webhooks, if the response body is not a valid JSON object, the contact will exit the workflow.
• 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 workflow 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 contact will exit the workflow. However, the workflow will continue to try those calls for future contacts.

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

# Further reading

• Wikipedia's Webhooks article
• Iterable's support guides about workflows