Workflow Webhooks

Workflow webhooks send data from Iterable to external servers (your own or third-party) as part of a workflow.

A workflow webhook makes a standard HTTP request to an external server, including relevant data in the request body (JSON or form URL-encoded). To authenticate with the external server, a webhook request can include authentication information.

Workflow webhooks have many uses. For example:

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

This document describes how to set up workflow webhooks in Iterable.

# Table of contents

# Creating test webhook URLs

When calling a webhook, Iterable sends data to a URL hosted on another server (your own or third-party). For debugging purposes, it can sometimes be helpful to use a test URL to make sure that Iterable makes the webhook calls when you expect and that they include all necessary data.

A few services that make it easy to set up test webhook endpoints include:

• Beeceptor
• Webhook.site
• Request Bin

# Types of webhooks

Iterable provides four types of workflow webhooks:

• Basic webhooks
  • Send POST requests to specified URLs, including information about their triggering events.
  • Are configured inline in a Call Webhook workflow node.
  • Discard the response returned by the server.
• Partner webhooks
  • Are pre-configured by Iterable and used for integrating with specific third-party services.
  • Are customized on the Integrations > Workflow Webhooks screen.
  • Are represented in an Iterable workflow by a Call Webhook node.
  • Discard the response returned by the server.
• Custom webhooks
  • Can use various HTTP methods (GET, PUT, POST, PATCH, and DELETE).
  • Can include a custom request body (including Handlebars merge parameters).
  • Are configured on the Integrations > Workflow Webhooks screen.
  • Are represented in an Iterable workflow by a Call Webhook node.
  • Discard the response returned by the server.
• Update user profile webhooks
  • Send a GET request to a specified URL.
  • Append a user's email address as a URL parameter.
  • Are represented in an Iterable workflow by an Update User Profile Webhook node.
  • Use the server's response to update the user's Iterable profile.

# 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, use a basic webhook.

# Setting up a basic webhook

To set up a basic webhook:

• Navigate to Messaging > Workflows.

• Open a workflow or create a new one.

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

  

• Configure the Call Webhook node:

  • Double-click the node to open it.

  

  • Make sure that Use Pre-Configured Workflow Webhook is disabled.

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

    TIPS

    • Use merge parameters to pass user profile fields to the webhook URL.
    • If the merge parameter's value may contain special characters or spaces, surround it with a call to {{#urlEncode}} to properly escape those characters.

    Example Endpoint URL:

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

  • If necessary, specify an Authorization Token.

    • This value will be sent as the Authorization header in the HTTP request.

  • Click Update Node to save the workflow node.

• Click Save to save the workflow.

• If necessary, enable the workflow with the toggle in the upper-left.

# Example basic webhook

Consider the following call to Iterable's POST /workflows/triggerWorkflow API:

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

Assuming that workflow 12345 has a Received API Trigger trigger node, this call would trigger the workflow.

If the workflow includes a basic webhook, it would send a POST request to a specified URL and include the following body:

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

# Partner webhooks

Pre-configured partner webhooks integrate Iterable workflows with various third-party tools. To use a partner webhook:

• Set up the partner webhook on the the Integrations > Workflow Webhooks screen.
• Add it to a workflow as a Call Webhook node.

# Setting up a partner webhook

To set up a partner webhook:

• Navigate to Integrations > Workflow Webhooks

• Click New Partner Webhook.

  

• Select the type of partner webhook to create and click Create Webhook.

  

• In the Create Workflow Webhook window, specify any necessary details. Greyed-out values are preset and cannot be changed.

  

  NOTE

  For API Key, specify an API key for the third-party service to which the workflow webhook will send data.

• Click Create Webhook.

• If necessary, finish configuring the partner webhook:

  • On the workflow webhook list, look at the row associated with the new webhook to determine if it requires any further configuration. For example, the Fields column may contain keys for which you must specify associated values:

  

  • To edit these fields, scroll to the right side of the webhook's row in the table and click Edit.

  • For each field, provide values or Handlebars references to user profile data. For example:

  

  NOTE

  This example matches the to[address_zip] form field (required by the third-party service) to the Iterable user profile field {{addresssZip}}, which (in the Iterable project associated with this example) stores the user's ZIP code.

  The specific user profile fields to reference depend on the structure of the data in your Iterable project.

  • Click Save to save your updates.

# Adding the partner webhook to a workflow

To add a partner webhook to an Iterable workflow:

• Navigate to Messaging > Workflows.

• Open a workflow or create a new one.

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

  

• Configure the Call Webhook node:

  • Double-click the node to open it.

  

  • Enable Use Pre-Configured Workflow Webhook.

  • In the Select a Webhook drop-down menu, choose the partner webhook create above.

  • Click Update Node to save the workflow node.

• Click Save to save the workflow.

• If necessary, enable the workflow with the toggle in the upper-left.

# Custom webhooks

For maximum control over a workflow webhook request, use a custom webhook. Custom webhooks can:

• Use various HTTP methods: GET, PUT, POST, PATCH, and DELETE.
• Specify custom request headers.
• Specify a fully custom request body (either JSON or form URL-encoded).

To use a custom webhook:

• Set up the custom webhook on the the Integrations > Workflow Webhooks screen.
• Add it to a workflow as a Call Webhook node.

# Setting up a custom webhook

To set up a custom webhook:

• Navigate to Integrations > Workflow Webhooks.

• Click New Webhook.

  

• Configure the new webhook:

  

  • Provide a Name.

  • Select the HTTP Method expected by the webhook's endpoint: GET, POST, PUT, PATCH, or DELETE. This cannot be changed after the webhook has been created.

    NOTE

    It is not possible for Iterable to use or store the data included in the server's response to a workflow webhook, regardless of which HTTP method the webhook uses.

  • For Content Type, select the type of data expected by the webhook's endpoint: JSON or FormUrlEncoded. This cannot be changed after the webhook has been created.

  • For Endpoint URL, specify the webhook URL to which Iterable should make the HTTP request:

    TIPS

    • Use Handlebars merge parameters to pass user profile fields to the webhook URL.
    • If a merge parameter's value might contain special characters or spaces, surround it with a call to {{#urlEncode}} to properly escape those characters.

    Example Endpoint URL:

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

  • Click Create Webhook.

• Further configure the workflow webhook:

  • Scroll to the far right of the webhook list and click Edit on the row associated with the new webhook.

    

  • Add custom HTTP headers to the webhook request by clicking Add HTTP Header in the HTTP Headers column.

    

  • Choose fields to include in the webhook's request body:

    IMPORTANT

    In a workflow webhook's request body, use Handlebars to reference user profile data. However, it's not possible to use Handlebars helper methods to manipulate the output format of the user profile data in the webhook request.

    • For JSON requests:

      • To select a user profile field to send in the request body, click Add User Field and use the Select a User Field drop-down menu. Repeat to specify multiple fields.

        

      • Alternatively, specify custom JSON for the webhook's request body by clicking Add Custom JSON. Use Handlebars to include user profile fields in the custom JSON. For example:

        {
            "person": {
                "firstName": "{{firstName}}",
                "lastName": "{{lastName}}",
                "email": "{{email}}"
            }
        }
        

      • If you specify user profile fields and custom JSON, Iterable adds the user profile fields to the top level of the custom JSON.

    • For form URL-encoded requests:

      • Add custom form fields to the request body by clicking Add Form Field.

        

      • Use Handlebars to set the value of any individual form URL-encoded field to a value from a user profile. For example, if a the form field has key first_name, the associated Handlebars might be {{firstName}} (depending on the field name your Iterable project uses to store first names).

    NOTE

    Choosing to include the default fields in a workflow webhook request (using the Include Default Fields column of the webhook definition) will include those fields at the top level of the webhook request.

# Adding the custom webhook to a workflow

To add the custom webhook to an Iterable workflow:

• Navigate to Messaging > Workflows.

• Open a workflow or create a new one.

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

  

• Configure the Call Webhook node:

  • Double-click the node to open 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.

• Click Save to save the workflow.

• If necessary, enable the workflow with the toggle in the upper-left.

# Example custom webhook

• Consider the following call to Iterable's POST /workflows/triggerWorkflow API:

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

  • If workflow 12345 has a Received API Trigger trigger node, this call will trigger the workflow.

• Assume that workflow 12345 includes a custom webhook with the following configuration:

  • Method: PUT

  • Content type: JSON

  • HTTP headers:

    • Authorization: 123456789

  • User fields:

    • toy (a field on the user's Iterable profile)

  • Custom JSON:

    {
        "city": "{{city}}",
        "state": "{{state}}"
    }
    

  • Default fields:

    • Enabled, to include email and workflowId in the webhook request

• For the above API request and custom workflow configuration, Iterable will send to the custom webhook's URL a PUT request similar to the following:

  • Custom HTTP headers:

    • Authorization: 123456789

  • Request body:

    {
        "promotionId": 123,
        "color": "red",
        "city": "San Francisco",
        "state": "California",
        "toy": "yo-yo",
        "email": "user@example.com",
        "workflowId": 12345
    }
    

# Update user profile webhooks

To call a webhook and use the server's response to update the user's Iterable profile, use an update user profile webhook.

An update user profile webhook:

• Makes a GET request to a specified URL, appending the user's email address as a URL parameter.
• Uses the request's JSON response 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:

• Navigate to Messaging > Workflows.

• Open a workflow or create a new one.

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

  

• Configure the Update User Profile Webhook node:

  • Double-click the node to open it.

  

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

    TIPS

    • Use Handlebars merge parameters to pass user profile fields to the webhook URL.
    • If a merge parameter's value might contain special characters or whitespace, surround it with a call to {{#urlEncode}} to properly escape those characters.
    • Do not include an email parameter, since Iterable will automatically append this to the URL when making the request.

    Example Endpoint URL:

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

  • If necessary, specify an Authorization Token. Iterable uses this for the value of the Authorization header in the webhook request.

  • Click Update Node to save the workflow node.

• Click Save to save the workflow.

• If necessary, enable the workflow with the toggle in the upper-left.

# Example update user profile webhook response

Assume an Iterable workflow made an update user profile webhook request for user test.user@iterable.com to an external server, and received a response containing the following JSON:

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

Iterable would use this response to update the user profile for test.user@iterable.com to have a firstName of "Test" and a lastName of "User".

# Errors

Workflow webhooks respond to HTTP status codes as follow:

• 200 (Success)
  • Continue to next step in the workflow
• 429 (Too Many requests)
  • Retry every three minutes, stopping after three attempts
• 4XX (Invalid Parameters or URL)
  • Stop
• 502, 503, 504 (Server Error)
  • Retry every three minutes, stopping after three attempts
• All other codes
  • Stop

Other errors:

• If the webhook has an invalid URL or yields an SSL exception, the workflow will stop processing for that user.

• For update user profile webhooks, if the response body is not a valid JSON object, the workflow will stop processing for that user.

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

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

# Further reading

• To learn more about webhooks in general, read Wikipedia's Webhooks article.
• Read the various workflow-related guides for more information about creating Iterable workflows.