Three systems need to hear from Klaviyo in near real time:
- The loyalty program needs to add points after a customer places an order.
- The helpdesk needs a ticket when a VIP abandons checkout.
- The CRM needs every email and text messaging unsubscribe (and spam complaint), so it never sends marketing to someone who opted out.
Use a webhook when a downstream system needs to react to a single Klaviyo event in near real time, such as an unsubscribe, a bounce, or a customer reaching a flow step, and the payload per event is small.
Webhooks only send new events going forward. For historical or bulk exports, use the APIs or SFTP instead.
All three of these use cases push data out of Klaviyo and will use either a system or a flow webhook.
But, what is the difference? The table below walks you through the difference between flow webhooks and system webhooks.
Flow webhook | System webhook | |
|---|---|---|
Summary (what it is) | An action step inside a flow that sends a custom HTTP POST with a JSON body you write using profile and event variables. | An account-level subscription to event "topics" (e.g., Unsubscribed from Email Marketing) that Klaviyo pushes to your endpoint in a fixed, standardized payload. |
When to use it | When you need conditional logic, timing, or a custom payload shape. The trigger is something that can start a flow. | When you need a reliable firehose of specific Klaviyo events (often consent and deliverability events) regardless of any flow. |
Use cases | Poppy & Pine uses it to: add loyalty points after Placed Order; create a helpdesk ticket when a VIP abandons checkout; notify a sales rep's CRM when a lead enters a high-intent segment. | Poppy & Pine uses it to: sync email and text messaging unsubscribes and spam complaints to the CRM (the focus of this lesson); stream bounces to the data quality tool. Also common: send review submissions to a product team's system. |
Payload | One request per profile with a body you design. | Batches events: any single request may include up to 1,000 events, which can come from multiple topics. |
Triggers | Limited to events that can trigger a flow. Events that don't trigger a flow, such as Unsubscribed from List, cannot be used. | Covers many events flow webhooks can't, such as Received Email, Clicked Email, and Marked Email as Spam. Topics depend on the metrics in the account, so confirm them with Get Webhook Topics. |
Security | Relies on headers you add (API key, bearer token). Requests include an X-Klaviyo-Flow-ID header containing the ID of the flow responsible for the request. | Includes a Klaviyo-Signature header with an HMAC-SHA256 signature you use to verify the request came from Klaviyo. |
Constraints | POST-only. The payload can include the triggering event and profile data, but not actions that happen later in the flow, like an email sent further down. | Plan-gated. Only available with Advanced KDP or to app partners using OAuth. Maximum of 10 webhooks per account. Can take up to 3 minutes to start sending events after you create it. Sends up to 10 requests at once, so make sure your endpoint can handle the load. |
Klaviyo Support can't help configure or troubleshoot webhooks, so plan to debug them yourself. For flow webhooks, start with the webhook's activity in the flow.
Common gotchas
System webhooks expect a 200, 201, or 202 within 5 seconds. Anything else counts as a failure and gets retried, so return 202 once the payload is safely queued.
Acknowledge immediately with 202, put the payload on a queue, and process asynchronously.
If a webhook remains in an error state for over 48 hours, it becomes disabled, and after re-enabling, Klaviyo only sends new events. Monitor the enabled field and build a backfill script before go-live, using the Get Events endpoint filtered by metric_id.
Header values are partially hashed for security, so after saving you can't read back the secret you entered, and edits made without clicking Save are lost when you close the panel. Store header values in a password manager or secrets vault, click Save before testing or navigating away, and re-enter the full header value whenever you edit it.
Flow bodies use Django-style variables, so a value with quotes, line breaks, or an empty property can break the JSON. Use default filters for optional properties and test with a profile that has messy data.
System webhooks expect a 200, 201, or 202 within 5 seconds. Anything else counts as a failure and gets retried, so return 202 once the payload is safely queued.
Acknowledge immediately with 202, put the payload on a queue, and process asynchronously.
If a webhook remains in an error state for over 48 hours, it becomes disabled, and after re-enabling, Klaviyo only sends new events. Monitor the enabled field and build a backfill script before go-live, using the Get Events endpoint filtered by metric_id.
Header values are partially hashed for security, so after saving you can't read back the secret you entered, and edits made without clicking Save are lost when you close the panel. Store header values in a password manager or secrets vault, click Save before testing or navigating away, and re-enter the full header value whenever you edit it.
Flow bodies use Django-style variables, so a value with quotes, line breaks, or an empty property can break the JSON. Use default filters for optional properties and test with a profile that has messy data.