Webhooks Overview

Webhooks connect Iterable to external apps and services through outbound HTTP calls. Depending on how you configure them, you can use webhooks to push data to external systems, pull real-time data from external sources into a journey, or both—without manually keeping information in sync across the apps your company uses.

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. Journey webhooks are used by two different tile types—Webhook tiles and Live Data tiles—which differ in how they handle the response from your endpoint.

	System webhooks	Webhook tile	Live Data tile (beta)
Trigger	A project-level system event (email send, SMS open, etc.)	A user reaching a step in a journey	A user reaching a step in a journey
HTTP method	POST only	Configurable (GET, POST, PUT, PATCH, DELETE)	Configurable (GET, POST, PUT, PATCH, DELETE)
Response handling	Discarded	Discarded	Parsed and stored as liveData for downstream tiles
Scope	All matching events in a project	One journey	One journey
Requires a saved journey webhook?	No	Optional	Yes, with Data Retrieval enabled
Primary use case	Monitor events, send data to BI tools, trigger external workflows	Send data to external services at a journey step	Fetch real-time data for in-journey decisioning and personalization

# System webhooks

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

Iterable sends system webhooks requests when a triggering event occurs. For example, if you set up a webhook to send when a user replies to an SMS (SMS Received webhook), then when your project receives an inbound SMS message, Iterable sends a request to the specified endpoint URL.

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

# Journey webhooks

Journey webhooks are outbound HTTP calls that Iterable makes to an external endpoint when a user reaches a specific step in a journey. You configure the HTTP method (GET, POST, PUT, PATCH, or DELETE) on the journey webhook itself. Journey webhooks are used by two different tile types.

# Webhook tiles

Webhook tiles send data from Iterable to an external server or service when a user reaches that step in a journey. Iterable discards any response from the server.

You can use Webhook tiles to:

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

# Live Data tiles (beta)

Live Data tiles also make an outbound call to a journey webhook endpoint—using the same configured HTTP method—but capture the response and make it available to downstream tiles in the journey via liveData references. This allows real-time decisioning and personalization based on external data, such as checking inventory levels, loyalty tier status, or offer eligibility before sending a message.

To use a Live Data tile, you must first configure a journey webhook with Data Retrieval enabled and define which fields from the response to expose. To learn more, see Journey Live Data Overview.

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