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.

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

There are two types of webhooks which you can use as workflow actions: Call Webhook and Update User Profile Webhook.

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. It 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 http://requestb.in. This will create an endpoint that you can point the webhook.

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 Update User Profile Webhook, you can use merge parameters to the webhook URLs, such as 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 & Update User Profile Webhook in workflows:

• HTTP Status
• 200: Continue to next step
• 400-499: Stop
• 500-599: Retry every 3 minutes
• 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).