Webhooks Overview

Webhooks send real-time data from Iterable to other apps and services. If you're not familiar with webhooks, they're actually pretty simple: webhooks are a way for apps to "talk" to each other. 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 as soon as something new happens in Iterable.

You can set up your 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.

Iterable sends webhooks as HTTP POST requests to a URL that you specify.

# Parts of a webhook

Generally, Iterable webhooks have these parts:

• 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 send from Iterable: system webhooks and journey webhooks. Each type of webhook sends data at different times and for different reasons.

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

# 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 set up a Call Webhook tile, which sends the webhook every time a user reaches that specific node in 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.
• And much more!

# 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 authorization 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 only Iterable IPs - If you want to restrict access to your webhook endpoint to only Iterable's servers, you can allow requests from Iterable's IP addresses.

# HTTP headers

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

System webhooks support:

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

Journey webhooks support:

• Basic HTTP authorization
• 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.

# Allowing Iterable's IP addresses

If you want to restrict access to your webhook to only Iterable's servers, you can allow requests from Iterable's IP addresses. This is a good way to make sure that only Iterable can access your webhook.

For a list of Iterable's currently circulating IP addresses, you can programmatically retrieve them from this location: https://api.iterable.com/ip-ranges.json. This list contains the IP addresses used for webhooks and data feeds.

# Refresh interval and changes to Iterable's IP addresses

Iterable's list of IP addresses is programatically refreshed every one hour (3600s), but it isn't a dynamic list. The list remains effectively static, but we refresh it every hour to accommodate potential future additions or changes to Iterable's IP addresses. The refresh process takes five minutes for the changes to take effect.

Iterable reserves capacity on the list for future growth, so it isn't expected to change frequently. However, in the event of a disaster recovery scenario, the entire list can change within that five-minute period.

To ensure you don't miss any IP addresses, we always maintain a capacity of three unused IP addresses on the list for future growth. This means that when we add new IP addresses, we add them to the list and reserve them for later, and begin using the IPs that were previously reserved. This way, we can ensure that the list is always up-to-date with IPs that are in use, and that you don't miss any changes to IP addresses.

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