Skip to main content

Get Data Out of Klaviyo

Course overview
Lesson
5 min read

Push data from Klaviyo using webhooks

Scheduled pulls work great for reports, but they're too slow when another system needs to react the moment something happens in Klaviyo. That's the next stop on Poppy & Pine's integration roadmap.

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

Before Poppy & Pine's webhooks go live, here's what commonly trips teams up. Each card shows a gotcha and an example. Flip it to see the workaround.
0 of 5 cards flipped
Question / Term
System webhooks only accept certain status codes. An endpoint returns 204 No Content for a system webhook. That's a "success" by HTTP standards, but it's not in Klaviyo's accepted list, so the request is treated as failed and retried.
Answer / Definition

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.

Question / Term
Slow endpoints fail system webhooks. A CRM sync that looks up the contact and writes three records before responding regularly exceeds 5 seconds during campaign sends. It generates retry storms and duplicates.
Answer / Definition

Acknowledge immediately with 202, put the payload on a queue, and process asynchronously.

Question / Term
System webhooks auto-disable and do not backfill. An endpoint is down over a long weekend. Monday's re-enable silently misses three days of unsubscribes, which is a compliance risk.
Answer / Definition

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.

Question / Term
Flow webhook editor "data disappearing" on save. A developer reopens the webhook to change the body. The masked token gets re-saved incorrectly, and the receiving API starts returning 401s that show up only in the skipped queue.
Answer / Definition

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.

Question / Term
Invalid JSON from template variables. A customer's address contains a quotation mark. The payload becomes invalid JSON, and only that profile fails.
Answer / Definition

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.

Activity: Flow webhook or system webhook?

Poppy & Pine's teams want Klaviyo to push data to other systems. Sort each request into the webhook type you'd use.
Notify a sales rep's CRM when a lead enters a high-intent segment.
Add loyalty points after a customer places an order.
Create a helpdesk ticket when a VIP abandons checkout.
Send every email click to the product analytics tool.
Sync email and text messaging unsubscribes and spam complaints to our CRM.
Stream bounces to our data quality tool.
Send every delivered email to our data warehouse.
Flow webhook
System webhook
Push data from Klaviyo using webhooks