Understand webhooks in Klaviyo's CDP

You will learn

Learn about webhooks, and how you can use them to send information to your third-party applications in response to events captured in Klaviyo. For more detailed information on how to receive system webhooks, head to our developer resource on working with system webhooks.

What are webhooks?

Webhooks allow Klaviyo to pass information or “call” other applications, tools, and servers via HTTP requests. They can send information about an event that has happened (e.g. an order placed, a new customer subscribed, etc) or notify your external systems that the event has occurred.

Klaviyo supports 2 kinds of webhooks:

1. Webhooks in Klaviyo CDP
   Webhooks available as part of Klaviyo CDP are used to notify your external systems that a particular event has occurred, and allow you to send information in response to a wide array of events without the limitations of being in a Flow.
2. Flow webhooks
   Flow webhooks are only available within the Flows interface, and are triggered when the Flow reaches a certain stage or step. They can be used to send data about the event or recipient that triggered the Flow.

Key components of webhooks

Webhooks are made of a few key components:

• Topic
  The event that causes a webhook to fire
• Body (or “the payload”)
  The data that the webhook sends.
• Headers
  A place to pass additional information (such as authentication)

How do webhooks in Klaviyo CDP differ from Flow webhooks?

You can use webhooks in Klaviyo's CDP or Flow webhooks depending on your needs.

Events included

Flow webhooks can only respond to a subset of Klaviyo events, and do not support message related events like Unsubscribed, Received email, or Clicked email as flows generally end with message receipt rather than begin with them. Meanwhile, webhooks in the Klaviyo CDP allow you to send information in response to any event in your account.

These include:

• Email events (e.g., Received email, Clicked email, Marked email as spam, Unsubscribe)
• SMS events (e.g., Sent SMS, Received SMS)
• Push notification events (e.g., Received push, Bounced push)
• Events from integrations ( i.e., events from first-party integrations created by Klaviyo)
• API events (e.g., events synced through Klaviyo’s APIs)

Payload

Flow webhooks allow you to customize the data included in the request, but you must manually construct the payload. Meanwhile, webhooks in Klaviyo CDP use a prebuilt payload that does not require any manual work on your end, and are used to notify external systems that an event has occurred.

Flow limitations

Flow webhooks must be configured within the Flows interface, and do not allow you to use several triggers at once. Different triggers must be created through individual Flows, and are dependent on the Flow’s overall status (e.g., a flow in draft would not send data through the Flow webhook). Meanwhile, webhooks in Klaviyo CDP exist outside of the Flows interface, and are not dependent on the series of steps leading up the webhook action like a Flow webhook.

Set up webhooks

To set up a webhook in Klaviyo, navigate to Webhooks under CDP > Data managment > Webhooks in Klaviyo.

1. To add a new webhook, click the Create webhook button.
2. On the Create a webhook modal, enter the information. This includes:
• Name
  How you’ll identify your webhook.
• Endpoint URL
  The URL associated with the destination for the webhook request.
• Secret key
  A unique identifier to identify Klaviyo webhook requests in your other systems.
• Description
  An optional description for your webhook.
3. In the Topics section, choose the events that you would like to trigger the webhook notification.

Once you have created your webhook, it will be listed on the Webhooks page along with the:

• Webhook name
• Webhook URL
• Time of the latest sync
• Status

You can delete or disable your webhook using the menu next to the item.

Test system webhooks 

When setting up a webhook in Klaviyo, you can test it to make sure that the connection is successful. To test your webhook, use the Test webhook button after entering the required fields.

A menu will appear where you can select a topic and send a test to your callback URL. 

After performing the test, you’ll see a message indicating whether it was successful, along with the header and body for the request populated in the Response tab.

Example payload

Below is an example of the payload for a webhook request in response to the Email delivered topic. 

{
  "meta": {
    "timestamp": "2023-08-10T07:25:23.700369+00:00",
    "klaviyo_webhook_id": "ID",
    "version": "2023-06-03"
  },
  "data": [
    {
      "topic": "event: email_delivered",
      "external_id": "ID",
      "payload": {
        "data": {
          "id": "ID",
          "type": "event",
          "links": {
            "self": "https://a.klaviyo.com/api/events/ID/"
          },
          "attributes": {
            "uuid": "96150200-374e-11ee-8001-a163313bc6c2",
            "datetime": "2023-08-10 07:21:56+00:00",
            "timestamp": 1691652116,
            "event_properties": {
              "$ESP": 0,
              "Subject": "? Free (Cool!) Swag Alert ?",
              "$message": "01H7F525FKR31P27Y7PNGVBBKK",
              "$event_id": "01H7F525FKR31P27Y7PNGVBBKK:125423419905414052533228990613763937641",
              "$group_ids": [
                "V7adxq"
              ],
              "$attribution": {
                "$send_ts": 0,
                "$attributed_event_id": ""
              },
              "Email Domain": "klaviyo-demo.com",
              "Campaign Name": "Daily Newsletter: 2023-08-10",
              "Inbox Provider": "Amazon SES Inbound",
              "$_cohort$message_send_cohort": "1691652081:01H7F525FKR31P27Y7PNGVBBKK"
            }
          },
          "relationships": {
            "metric": {
              "data": {
                "id": "ID",
                "type": "metric"
              },
              "links": {
                "self": "https://a.klaviyo.com/api/events/ID/relationships/metric/",
                "related": "https://a.klaviyo.com/api/events/ID/metric/"
              }
            },
            "profile": {
              "data": {
                "id": "ID",
                "type": "profile"
              },
              "links": {
                "self": "https://a.klaviyo.com/api/events/ID/relationships/profile/",
                "related": "https://a.klaviyo.com/api/events/ID/profile/"
              }
            }
          }
        }
      }
    },
  

Additional resources

How to add a webhook action to a Flow

Understanding Klaviyo webhooks

Working with system webhooks (Klaviyo's Webhooks API)