Using Webhooks

Webhooks are a great way of extending what you can do with Iterable and how it interacts with other systems, including your own backend. A webhook can be triggered by any event and can then in turn trigger something to happen in another system or server. There are two ways to use webhooks in Iterable.

NOTE: For security reasons, Iterable strongly recommends that customers make use of the provided authorization functionality (see details below) when configuring webhooks. The authorization can be included as a header in the webhook call or as a parameter in the webhook URL. Because IPs are not necessarily static and are potentially vulnerable to spoofing, Iterable will not provide IPs for whitelisting.

Table of Contents

System Webhooks

Workflow Webhooks

• Creating Workflow Webhooks
  • Inkit Integration
  • Lob Integration
• Types of Webhook Workflow Actions
  • Call Webhook
  • Update User Profile Webhook

Webhook Error Handling Logic

System Webhooks

You can set up a webhook by going to Integrations--> Webhooks on the left menu. This is useful for sending data about Iterable campaigns to another system. The webhook events will include the campaign metrics and the campaignName, templateName and emailSubject.

These simple webhooks will send a POST request with two headers to your specified endpoint. The headers are: Content-Type, value = application/json, and Authorization: authType + " " + authToken. So for example if you select OAuth, and J1qK1c18UUGJFAzz9xnH56584l4 is your token, then the header will be Authorization: OAuth J1qK1c18UUGJFAzz9xnH56584l4. The body of the request will contain the following fields: email, eventName, and any other data that was in the triggering event inside a field called dataFields.

To learn more about system webhooks and the sample responses for each type of event, please refer to this support page. 

Workflow Webhooks

Call Webhook

Use the Call Webhook action if you would like Iterable to make an HTTP request to another service to trigger an action. For the workflow webhooks, there is no authentication scheme. When using a JSON formatted webhook, the Call Webhook action will make a POST request with the data of the triggering event to your specified endpoint, with JSON Content-Type, value = application/json.

For testing, we recommend a tool called Beeceptor or Webhook Tester. This will create an endpoint that you can point the webhook to.

NOTE: We have encountered issues when using the https://requestb.in/ service to test webhook calls, so we do not recommend it as a testing tool.

Sample workflow

Sample body for triggerWorkflow API call

{
        "email":"sherry@iterable.com",
        "workflowId":2553,
        "dataFields":{
          "firstName":"Sherry",
          "lastName":"Chao"
   }
}

Sample output

{
     "firstName":"Sherry",
     "lastName":"Chao"
}

Update User Profile Webhook

Use this action if you would like Iterable to make an HTTP GET request to your database with the query parameter email. It expects a JSON response used to update the user’s profile within Iterable.  

For the Update User Profile Webhook, you can use merge parameters in the webhook URL, for example http://api.mysite.com/update?email={{email}}&firstName={{firstName}}.

Sample workflow:

Sample body

{   
"email”: "sherry@iterable.com”
}

Sample output

{
  "email":"sherry@iterable.com",
  "dataFields":{
    "firstName":"Sherry",
    "lastName":"Chao"
  }
}

Click here to learn more about Iterable workflows.

Webhook Error Handling Logic

For Call Webhook and Update User Profile Webhooks in workflows:

• HTTP Status
• 200: Continue to next step
• 400-499: Stop
• 500-599: Retry every 3 minutes, stopping after 5 attempts
• All other codes: Stop
• Invalid endpoint url or SSL exception
• Stop

Update User Profile Webhook only:

• Body is not a JSON object
• Stop

If the Update User Profile webhook times out after 10 seconds, returns a non-200 HTTP code, or isn't valid JSON, it will be retried after 3 minutes.

Otherwise, the resulting JSON will be saved to the user's profile and the workflow will continue after a short delay (to ensure that the user profile will be up to date by the next step).

In the event of workflow webhook errors, you will also receive a notification in your notification center: