How to add a webhook action to a flow
Learn how to add a webhook action into a Klaviyo flow to perform HTTP POST requests.
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.
- 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.
![A modal appears when adding a webhook to a flow if two-factor authentication is not enabled](https://files.readme.io/a828668-twostepauthreq.png)
- After configuring two-step authentication, click Continue.
- 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
- In the left sidebar of the flow builder, click on the Webhook action and drag into your flow.
![The Webhooks action in the flow builder, which you can drag and drop into any part of a flow](https://files.readme.io/9228142-small-Webhook.jpg)
- 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
![Webhook action configuration with an example destination URL](https://files.readme.io/0b33a73-webhookactivity.png)
- 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.
- Under Body, input your payload as a JSON block. Only JSON formatting is supported for webhooks.
![Example of a JSON payload for a webhook](https://files.readme.io/bcc208d-JSONbody.png)
- 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.
![Preview Profile Info window that shows all profile properties for an individual](https://files.readme.io/74e8f5b-previewprofile.png)
- 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
Updated 2 months ago