This guide is intended for developers with experience in setting up and validating webhooks. It’s important to note that Klaviyo Support cannot help configure or troubleshoot your webhooks, as each use case is unique to the particular third-party system.

If you are not a developer but want to learn what you can do with webhooks, read our Getting started with Klaviyo webhooks guide.

Before you begin

Two-step authentication is required to use Klaviyo webhooks. You must be a Manager, Admin, or Owner to enable two-step authentication as well as to add or edit webhooks.

1. The first time you add a webhook within a flow and do not have two-step authentication turned on, a modal will appear reminding you to set up two-step authentication. This modal will no longer show once two-step authentication has been properly configured. This will be a requirement for each individual user who is editing or adding webhook actions.
   Click Set Up Two-Step Authentication to be taken to your account settings page in order to enable two-step authentication.

2. After configuring two-step authentication, click Continue.
3. If two-step authentication has been enabled, the modal will disappear, and you can continue editing or setting up the flow.
   Otherwise, if there is an issue verifying that two-step authentication has been enabled, an error message will appear. If this is the case, please click Set Up Two-Step Authentication again to be taken back to your account settings to confirm it is enabled.

If you need assistance, please see our Help Center guide on how to enable two-step authentication.

How to configure a webhook

1. In the left sidebar of the flow builder, click on the Webhook action and drag into your flow.

2. Input the URL for the endpoint the webhook should send to. The URL must meet the following conditions:

• Be a valid URL format
• Start with HTTPS://
• Not have a self-signed SSL certificate
• Not redirect to another URL

3. Add any header(s) you want to include (e.g., for authentication). To do so, click + Add Headers and then input the key value pair(s).

📘

In Klaviyo, all information for webhook headers are partially hashed for security purposes.

4. Under Body, input your payload as a JSON block. Only JSON formatting is supported for webhooks.

5. To add information related to the profile or triggering event, click either:

• View profile properties (for list-, segment-, and date property-triggered flows)
• View profile and event variables (for metric- and price drop-triggered flows).

This will open a preview panel, where you can copy and paste the variables into the payload.

6. Click Save to set the webhook live.

Klaviyo will provide a status on if the webhook setup was successful and if it fails, a description of the issue.

Klaviyo webhook capabilities

Type of requests

Webhooks in Klaviyo can only perform POST requests; you cannot use them for DELETE, GET, or any other type of HTTP request. Note that you should not use webhooks to subscribe profiles to new lists.

Triggers

In Klaviyo, webhooks are limited to events that can trigger a flow, including:

• Started Checkout
• Placed Order
• Viewed Product
• Subscribed to List
• Added to a Segment

Events that don’t trigger a flow, such as Unsubscribed from List, cannot be used for webhooks.

Properties and event variables

For list- and segment-triggered flows, you can pass profile properties. For any metric- or price drop-triggered flows, you can pass profile properties and dynamic event data associated with the triggering event. For instance, for a Placed Order event, you can include aspects such as the item(s) left behind, their price, the total for the cart, as well as the customer’s name and address.

For event-based flows, you cannot pass information about any subsequent actions taken by the customer. For instance, if you have a flow triggered by a Viewed Product event and then send an email, you cannot use the webhook to pass data about the sent email

Django logic

Similar to conditional logic for templates, you can add Django logic into the payload of the webhook. This allows you to send a webhook that can add, subtract, etc., allowing for addition and subtraction. Further, you can include special logic to send, for example, only certain pieces of the value.

For instance, say that you run a loyalty program. By including django logic, you can trigger a webhook so that whenever a customer makes a purchase, it adds the same number of points to their profile in your program.

Currently, coupon codes, web feeds, and product feeds are not supported.

Success responses and retries

Klaviyo considers 2xx responses as a successfully sent POST request. Anything that is not a 2xx response will be addressed based on whether it is a retry-able error.

If it is retry-able, Klaviyo will automatically retry to send the POST request with an exponential backoff interval, and then placed into a failed queue in the Webhook Analytics page after multiple retries.

If it is not a retry-able error, the request is sent to the Skipped queue.

Originating flow information

HTTP requests coming from flow webhook actions include a request header called X-Klaviyo-Flow-ID. The value of this header will equal the ID of the flow containing the flow webhook action responsible for the HTTP request.

To retrieve information about that flow programmatically, use our Get Flow API

Additional resources

• Getting started with webhooks
• Understanding webhook status codes