Webhooks Overview

Webhooks sync data between apps in response to a trigger. Instead of manually updating information across all of the apps your company uses, you can connect those apps to Iterable with webhooks so that they automatically update when something new happens.

You can set up webhooks to send relevant information in each request — like a campaign or event name, a user's email address, or authentication credentials.

While not a replacement for the Iterable API, webhooks can be a powerful tool for integrating Iterable with other systems.

# In this article

# Using webhooks in Iterable

You can configure Iterable to call a webhook each time a specific event occurs, like when a user subscribes to a list, opens an email, or clicks a link. You can also set up webhooks to send data at a specific time, like when a campaign is sent or when a user enters a journey.

# Webhook components

Generally, Iterable webhooks have the following components:

• A destination URL - You must provide Iterable with a URL to send the webhook to. This is your third-party app or service that you want to send data to.

• HTTP headers - Iterable includes headers in the webhook request to help you authenticate the request. You can also include custom headers in the request to send additional information.

• A payload with JSON data - Iterable sends data in JSON format in the body of the request. The data in the payload depends on the type of webhook you're using, the triggering event, and other configurations in your project. The payload data is always related to the event that triggered the webhook to send. For some examples, see system webhook examples.

# Types of webhooks

There are two kinds of webhooks that you can use in Iterable: system webhooks and journey webhooks.

# System webhooks

System webhooks can help you monitor what's going on in your Iterable project. You can have Iterable call a webhook every time a system event occurs (like an email send, a push notification open, an SMS bounce, or a list unsubscribe).

System webhooks always send when a triggering event occurs. For example, if you set up a webhook to send when a user replies to a SMS (SMS Received webhook), then every time your project receives a reply to an SMS, Iterable sends a webhook to the URL you specify.

Calls made to Iterable system webhooks endpoints are HTTP(S) POST requests. When a successful call occurs, Iterable sends data to the specified endpoint URL and discards any response received from the server.

# Journey webhooks

Journey webhooks let you connect other apps and services to your Iterable project by sending data at specific points in a journey.

To do this, you can configure a Webhook tile or Live Data tile (beta) to call your specified journey webhook every time a user reaches that stage of a journey.

Journey webhooks can do things like:

• Update a user's Iterable profile
• Send data to Segment
• Set up direct mail sends with Inkit
• Trigger an action in Zapier
• Launch NPS surveys with Delighted

Journey webhooks can be configured to make HTTP(S) POST, GET, PUT, PATCH, or DELETE requests. When a successful call occurs, Iterable sends data to the specified endpoint URL. In general, any response received from the server is discarded. However, there are two exceptions to this:

• When the call is a GET request made from a User Profile journey tile, the specified data from the response is saved to the user's profile.

• When a Live Data tile calls a journey webhook that has Data Retrieval enabled, the response data is captured and persists for the duration of the user's path through the journey. When the user exits the journey, the response data is discarded.

# Webhook security

Security is important when you're setting up webhooks. Webhooks can be a vulnerability if they're not set up correctly and securely.

Here are a few ways you can make sure your webhooks are secure:

• Use HTTPS - Iterable requires webhooks to use HTTPS. This helps keep your data secure. Make sure your webhook URL starts with https:// instead of http://.

• Authenticate your requests - Iterable makes it easy to include Basic or OAuth 2.0 HTTP authentication headers in your webhook requests to make sure only the apps you trust can access your webhook.

• Use custom headers - You can include custom headers in your webhook requests to make sure that the request is coming from Iterable. This is how you can authenticate the request using a secret like an API key.

• Allow Iterable IP addresses - If you want to restrict access to your webhook endpoint to only Iterable's servers, you can allow requests from Iterable's IP addresses. To learn more, see Allowing Iterable IP Addresses.

# HTTP headers

When you set up a webhook, you can choose to authenticate by including HTTP authentication headers in your request. Iterable generally supports basic and OAuth 2.0 HTTP authentication headers.

System webhooks support:

• Basic HTTP authentication
• OAuth 2.0 bearer tokens
• Custom HTTP headers (use for API keys, for example)

Journey webhooks support:

• Basic HTTP authentication
• OAuth 2.0 client credentials that generate access tokens
• Custom HTTP headers (use for API keys, for example)

You can also add custom HTTP headers as-needed to build your own solution for authenticating requests.

# Testing webhooks

When you set up a webhook, it's a good idea to test it to make sure it's working correctly. You will also need to view the available data that your webhook sends to make sure it's what you expect.

While Iterable provides examples of webhook payloads in our documentation, these examples may not cover all the data that your webhook sends.

You can use a third-party tool like RequestBin to test your webhooks. A service like these can provide you with a URL that you can use to test your webhook requests. This can help you make sure your webhook is set up correctly and provide a way to inspect the data that your webhook sends.