Webhooks API overview

🚧

The endpoints referenced in this guide are in beta and subject to change.

A beta revision header (2024-05-15.pre) is required to use our Webhooks API. Klaviyo APIs in beta are not intended for use in production. If you have feedback about these endpoints, fill out our Webhooks feedback form.

Before you begin

Note that only CDP customers can manage system webhooks in Klaviyo’s UI. Klaviyo app partners can access and manage system webhooks via OAuth and our Webhooks API.

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

Klaviyo offers two types of webhooks:

• Flow webhooks

  A flow action that sends a custom, manually configured payload to an HTTP endpoint.

• System webhooks

  A notification with a predefined payload format triggered by specific events within Klaviyo, for example, an email being sent, an SMS being clicked, or a push notification being delivered.

Our Webhooks API specifically handles system webhook management, i.e., it allows you to forward Klaviyo events to external endpoints of your choosing. The Klaviyo events, or “topics” you can currently trigger off of include:

• Email events (e.g., Received email, Clicked email, Marked email as spam)
• SMS events (e.g., Sent SMS, Received SMS)
• Push notification events (e.g., Received Push, Bounced Push)
• Review events (e.g. Ready to Review, Submitted Review)
• Consent events (e.g. Subscribed to sms marketing, Unsubscribed from email marketing, etc.)

📘

You can use the Get Topics endpoint to get a full list of topics. See our guide on Working with system webhooks for a comprehensive list of events and their corresponding topic IDs.

Data model

A webhook can have the following:

• id

  The webhook id.

• attributes

  • name

    The webhook name.

  • description

    The description of the webhook.

  • endpoint_url

    The URL associated with the destination for the webhook request.

  • enabled

    A boolean indicating whether the webhook is enabled or disabled.

  • created_at

    The date the webhook was created.

  • updated_at

    The date the webhook was last updated.

• relationships

  This object contains related resources, i.e., webhook topics. Learn more about relationships.

• webhook-topics

  Contains the webhook topic(s), e.g., a Sent SMS event.

Add scopes for webhooks

OAuth apps can use this API with an access token if they have been allowlisted by Klaviyo as part of this early release. Webhooks that are created by an OAuth application are scoped to the OAuth app that they're registered to. When a webhook is registered to an app, other apps can't view, modify, or delete it.

To use webhook endpoints, your OAuth app will need the following scopes:

• webhooks:read
• webhooks:write

When registering a new webhook, the topics subscribed will also be gated by additional API scopes. The current set of topics are event-based and will require events:read scopes. For example, if you send a request to create a webhook for SMS Sent events, your private key or bearer token will need the events:read scope (or else you will receive a 403 error).

Create your webhook subscription

Before creating your webhook subscription, review the following required fields for the API request body and what the response will look like. Then, review the sample code before making your request to Create Webhook Subscription.

Create Webhook Subscription request details

The following fields make up the Create Webhook Subscription request body:

• Name (required)

  How you’ll identify your webhook.

• Endpoint URL (required)
  The URL associated with the destination for the webhook request. The URL must:

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

• Topics (required)
  The event(s) that trigger the webhook.

• Secret key (required)
  Klaviyo utilizes HMAC-SHA256 to sign webhook requests with this secret key. This ensures that subscribers can verify the integrity and authenticity of data. It must be at least 16 characters in length.

• Description (optional)
  A description for your webhook.

Get Webhook Subscription response details

All fields from the request body will be returned, except the secret key, and the endpoint URL will be truncated. The following additional field will be included in the response:

• Enabled
  A boolean option indicating whether the webhook is enabled or disabled.

Create Webhook Subscription example request

Below is an example request to the Create Webhook Subscription endpoint:

{
  "data": {
    "type": "webhook",
    "attributes": {
        "name": "SMS Conversation Webhook",
        "endpoint_url": "https://www.example.com/klaviyo-events",
        “secret_key”: “sEcReTkEy12345678”, 
        “description”: "This webhook triggers sms sent and sms received events”,
    },
    "relationships": {
      "webhook-topics": {
        "data": [
          {
            "type": "webhook-topic",
            "id": "event:klaviyo.sent_sms"
          },
          {
            "type": "webhook-topic",
            "id": "event:klaviyo.received_sms"
          }
        ]
      }
    }
  }
}

The 201 response to the above request would look something like this:

{
  "data": {
    "type": "webhook",
    "attributes": {
        "name": "SMS Conversation Webhook",
        "endpoint_url": "https://www.example.com/klaviyo-events",
        “enabled”: true,
        “created_at”: “2024-01-12T09:00:00Z”,
        “updated_at”: “2024-01-12T09:00:00Z”
    },
    "relationships": {
      "webhook-topics": {
        "data": [
          {
            "type": "webhook-topic",
            "id": "event:klaviyo.sent_sms"
          },
          {
            "type": "webhook-topic",
            "id": "event:klaviyo.received_sms"
          }
        ]
      }
    }
  }
}

Test your webhook

You can create a function in Napkin.io for easy testing. Napkin allows you to create and deploy serverless cloud functions instantly from within your browser.

Write a quick function for handling the webhook, click Deploy, and then copy the URL from Napkin to use as your endpoint_url.

When events related to the subscribed topics in the webhook occur in the account that has subscribed (e.g., an SMS is sent to a Klaviyo sending number and the webhook includes the sms.sent topic) the webhook will be triggered and you’ll see the details in the Events tab in Napkin, as shown below:

Limitations

• It can take up to 3 minutes for a webhook subscription to start forwarding events to the URL.
• Each Klaviyo account can have a maximum of 10 webhook subscriptions, whether created through the UI or API. There is no limit on the number of topics that a single webhook subscription can utilize.
• A webhook created via OAuth won’t be visible in Klaviyo’s UI, and UI-created webhooks won’t be visible to API calls from OAuth apps.
• The endpoint_url will be truncated when returned, as it may include sensitive contents.

Additional resources

• Learn more about creating webhooks via UI (Klaviyo CDP)
• Working with system webhooks