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.

#Table of contents

#System Webhooks

You can set up a webhook by navigating to Integrations > Webhooks. This is useful for sending data about Iterable campaigns to another system. The webhook events will include the campaign metrics and the campaign name, template name, and email subject.

These simple webhooks will send a POST request with two headers to your specified endpoint. The headers are:

• Content-Type: application/json

• Authorization: AUTH_TYPE AUTH_TOKEN

  For example, if you select OAuth, use a token of J1qK1c18UUGJFAzz9xnH56584l4, 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

#Creating workflow webhooks

Workflow webhooks support both JSON and the FormUrlEncoded content types. The FormUrlEncodedwebhook format allows Iterable to connect with other applications and leverage nearly any value from a user or event (such as cart abandonment). You can also use a combination of merge fields in the fields of the webhook to create highly personalized content.

#Inkit integration

Iterable has partnered with Inkit, a direct mail automation service, to seamlessly send postcards to your users. The Inkit webhook can be built as long as you have a pre-existing Inkit account set up. More about the Iterable and Inkit partnership can be found here.

The steps to get Inkit up and running are as follows:

1. Grab your API key and Template ID from the Inkit dashboard.

   • Your API key is located here.

   • The Template ID can be found within the URL for each template. For example:

     https://app.inkit.io/templates/design/bd9b0b8c-c47b-40ae-8787-80dd76f6d2bb
     

2. In Iterable, create a new workflow webhook by navigating to Workflows > Workflow Webhooks and clickingNew Webhook.

3. Fill in the webhook with the following details:

   • Name
   • Content Type: FormURLEncoded
   • Endpoint URL - https://internal.inkit.io/integrations/iterable/webhook

   

4. Scroll over to the right of your created webhook, and click on Edit to add in the remaining fields.

5. Add a HTTP Header for the Authorization key value pair, with your API key from Inkit.

6. Add the following mandatory fields to specify the recipient, using Iterable contact properties, and the template which should be sent out:

   • User profile fields:

     • first_name
     • last_name
     • address
     • address2
     • city
     • state
     • zip
     • country (must be a two-character code; for example, US)

   • template_id (Template ID from Inkit's end)

   

#Lob integration

Iterable has partnered with Lob to construct a specialized Lob webhook that is optimized for ease of use. The Lob webhook allows Iterable to seamlessly integrate with Lob by pre-populating the workflow webhook with all the fields you need in order to send a Lob postcard. As long as you have a pre-existing Lob account set up, this special webhook is available in Iterable. More about the Iterable and Lob integration can be found here.

The Lob webhook modal window is configured with URL validation and supports handlebar logic. Also, Iterable will automatically Base64 encode your API Key.

#Types of workflow actions for webhooks

There are two actions that webhooks can perform as workflow actions: Call Webhook and Update User ProfileWebhook.

#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.

To create a test webhook endpoint, try using Beeceptor, Webhook Tester, or Request Bin.

#Sample workflow using a call webhook

#API call to trigger a workflow

The /workflows/triggerWorkflow API can trigger a workflow such as the sample above.

• Sample request body:

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

• Sample response body:

  {
      "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 using a user profile webhook

• Sample request body:

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

• Sample response body:

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

For more information about Iterable workflows, take a look at the Workflow overview article.

#Webhook error handling logic

Call and update user profile webhooks in workflows respond as follow

Other errors:

• If the webhook has an invalid URL or encounters an SSL exception, the workflow will stop 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 isn't valid JSON, it will be retried after three 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: