openapi: 3.0.2
info:
  title: Klaviyo Accounts Webhooks API
  version: '2026-04-15'
  description: The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.
  contact:
    name: Klaviyo Developer Experience Team
    email: developers@klaviyo.com
    url: https://developers.klaviyo.com
  termsOfService: https://www.klaviyo.com/legal/api-terms
  license:
    name: License
    url: https://www.klaviyo.com/legal
servers:
- url: https://a.klaviyo.com
  description: Production
security:
- Klaviyo-API-Key: []
tags:
- name: Webhooks
  description: webhooks
paths:
  /api/webhooks:
    get:
      operationId: get_webhooks
      summary: Get Webhooks
      description: 'Get all webhooks in an account.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:read`'
      parameters:
      - name: fields[webhook]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - created_at
            - description
            - enabled
            - endpoint_url
            - name
            - updated_at
        explode: false
      - name: include
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#relationships
        schema:
          type: array
          items:
            type: string
            enum:
            - webhook-topics
        explode: false
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetWebhookResponseCollectionCompoundDocument'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:read
    post:
      operationId: create_webhook
      summary: Create Webhook
      description: 'Create a new Webhook<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:write`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/WebhookCreateQuery'
      responses:
        '201':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PostWebhookResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:write
  /api/webhooks/{id}:
    get:
      operationId: get_webhook
      summary: Get Webhook
      description: 'Get the webhook with the given ID.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:read`'
      parameters:
      - name: id
        in: path
        description: The ID of the webhook.
        required: true
        schema:
          description: The ID of the webhook.
          type: string
      - name: fields[webhook]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - created_at
            - description
            - enabled
            - endpoint_url
            - name
            - updated_at
        explode: false
      - name: include
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#relationships
        schema:
          type: array
          items:
            type: string
            enum:
            - webhook-topics
        explode: false
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetWebhookResponseCompoundDocument'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:read
    patch:
      operationId: update_webhook
      summary: Update Webhook
      description: 'Update the webhook with the given ID.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:write`'
      parameters:
      - name: id
        in: path
        description: The ID of the webhook.
        required: true
        schema:
          description: The ID of the webhook.
          type: string
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/WebhookPartialUpdateQuery'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PatchWebhookResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:write
    delete:
      operationId: delete_webhook
      summary: Delete Webhook
      description: 'Delete a webhook with the given ID.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:write`'
      parameters:
      - name: id
        in: path
        description: The ID of the webhook.
        required: true
        schema:
          description: The ID of the webhook.
          type: string
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '204':
          description: Success
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:write
  /api/webhook-topics:
    get:
      operationId: get_webhook_topics
      summary: Get Webhook Topics
      description: 'Get all webhook topics in a Klaviyo account.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:read`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetWebhookTopicResponseCollection'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:read
  /api/webhook-topics/{id}:
    get:
      operationId: get_webhook_topic
      summary: Get Webhook Topic
      description: 'Get the webhook topic with the given ID.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `15/m`


        **Scopes:**

        `webhooks:read`'
      parameters:
      - name: id
        in: path
        description: The ID of the webhook topic.
        required: true
        schema:
          description: The ID of the webhook topic.
          type: string
          example: event:klaviyo.sent_sms
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetWebhookTopicResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Webhooks
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 1/s
        steady: 15/m
      x-klaviyo-scopes:
      - webhooks:read
components:
  schemas:
    WebhookPartialUpdateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookPartialUpdateQueryResourceObject'
      required:
      - data
    GetWebhookResponseCompoundDocument:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookResponseObjectResource'
        included:
          type: array
          items:
            $ref: '#/components/schemas/WebhookTopicResponseObjectResource'
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    GetWebhookResponseCollectionCompoundDocument:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookResponseObjectResource'
        links:
          $ref: '#/components/schemas/CollectionLinks'
        included:
          type: array
          items:
            $ref: '#/components/schemas/WebhookTopicResponseObjectResource'
      required:
      - data
    WebhookTopicResponseObjectResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WebhookTopicEnum'
        id:
          description: The ID of the webhook topic.
          type: string
          example: event:klaviyo.sent_sms
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - type
      - id
      - links
    WebhookResponseObjectResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WebhookEnum'
        id:
          description: The ID of the webhook.
          type: string
          example: 01HF7AYTK76RHR4F17G6DGTRGF
        attributes:
          type: object
          properties:
            name:
              description: A name for the webhook.
              type: string
              example: My Webhook
            description:
              description: A description for the webhook.
              type: string
              example: A webhook for sms events
              nullable: true
            endpoint_url:
              description: The url to send webhook requests to, truncated for security.
              type: string
              example: https://www.example.com
            enabled:
              description: Is the webhook enabled.
              type: boolean
            created_at:
              description: Date and time when the webhook was created, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)
              type: string
              format: date-time
              example: '2022-11-08T01:23:45+00:00'
              nullable: true
            updated_at:
              description: Date and time when the webhook was last updated, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)
              type: string
              format: date-time
              example: '2022-11-08T01:23:45+00:00'
              nullable: true
          required:
          - name
          - endpoint_url
          - enabled
        relationships:
          type: object
          properties:
            webhook-topics:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    required:
                    - type
                    - id
                    properties:
                      type:
                        $ref: '#/components/schemas/WebhookTopicEnum'
                      id:
                        description: A topic the webhook is subscribed to.
                        type: string
                        example: event:klaviyo.sent_sms
                links:
                  $ref: '#/components/schemas/RelationshipLinks'
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - type
      - id
      - attributes
      - links
    WebhookCreateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookCreateQueryResourceObject'
      required:
      - data
    PostWebhookResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/WebhookEnum'
            id:
              description: The ID of the webhook.
              type: string
              example: 01HF7AYTK76RHR4F17G6DGTRGF
            attributes:
              type: object
              properties:
                name:
                  description: A name for the webhook.
                  type: string
                  example: My Webhook
                description:
                  description: A description for the webhook.
                  type: string
                  example: A webhook for sms events
                  nullable: true
                endpoint_url:
                  description: The url to send webhook requests to, truncated for security.
                  type: string
                  example: https://www.example.com
                enabled:
                  description: Is the webhook enabled.
                  type: boolean
                created_at:
                  description: Date and time when the webhook was created, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)
                  type: string
                  format: date-time
                  example: '2022-11-08T01:23:45+00:00'
                  nullable: true
                updated_at:
                  description: Date and time when the webhook was last updated, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)
                  type: string
                  format: date-time
                  example: '2022-11-08T01:23:45+00:00'
                  nullable: true
              required:
              - name
              - endpoint_url
              - enabled
            relationships:
              type: object
              properties:
                webhook-topics:
                  type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        required:
                        - type
                        - id
                        properties:
                          type:
                            $ref: '#/components/schemas/WebhookTopicEnum'
                          id:
                            description: A topic the webhook is subscribed to.
                            type: string
                            example: event:klaviyo.sent_sms
                    links:
                      $ref: '#/components/schemas/RelationshipLinks'
            links:
              $ref: '#/components/schemas/ObjectLinks'
          required:
          - type
          - id
          - attributes
          - links
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    WebhookTopicEnum:
      type: string
      enum:
      - webhook-topic
    WebhookPartialUpdateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WebhookEnum'
        id:
          description: The ID of the webhook.
          type: string
        attributes:
          type: object
          properties:
            name:
              description: A name for the webhook.
              type: string
              nullable: true
            description:
              description: A description for the webhook.
              type: string
              nullable: true
            endpoint_url:
              description: A url to send webhook calls to. Must be https.
              type: string
              example: https://www.example.com/example/path
              nullable: true
            secret_key:
              description: A secret key, that will be used for webhook request signing.
              type: string
              nullable: true
            enabled:
              description: Is the webhook enabled.
              type: boolean
              nullable: true
        relationships:
          type: object
          properties:
            webhook-topics:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    required:
                    - type
                    - id
                    properties:
                      type:
                        $ref: '#/components/schemas/WebhookTopicEnum'
                      id:
                        description: A list of topics to subscribe to.
                        type: string
                        example: event:klaviyo.sent_sms
      required:
      - type
      - id
      - attributes
    GetWebhookTopicResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WebhookTopicResponseObjectResource'
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    PatchWebhookResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/WebhookEnum'
            id:
              description: The ID of the webhook.
              type: string
              example: 01HF7AYTK76RHR4F17G6DGTRGF
            attributes:
              type: object
              properties:
                name:
                  description: A name for the webhook.
                  type: string
                  example: My Webhook
                description:
                  description: A description for the webhook.
                  type: string
                  example: A webhook for sms events
                  nullable: true
                endpoint_url:
                  description: The url to send webhook requests to, truncated for security.
                  type: string
                  example: https://www.example.com
                enabled:
                  description: Is the webhook enabled.
                  type: boolean
                created_at:
                  description: Date and time when the webhook was created, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)
                  type: string
                  format: date-time
                  example: '2022-11-08T01:23:45+00:00'
                  nullable: true
                updated_at:
                  description: Date and time when the webhook was last updated, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)
                  type: string
                  format: date-time
                  example: '2022-11-08T01:23:45+00:00'
                  nullable: true
              required:
              - name
              - endpoint_url
              - enabled
            relationships:
              type: object
              properties:
                webhook-topics:
                  type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        required:
                        - type
                        - id
                        properties:
                          type:
                            $ref: '#/components/schemas/WebhookTopicEnum'
                          id:
                            description: A topic the webhook is subscribed to.
                            type: string
                            example: event:klaviyo.sent_sms
                    links:
                      $ref: '#/components/schemas/RelationshipLinks'
            links:
              $ref: '#/components/schemas/ObjectLinks'
          required:
          - type
          - id
          - attributes
          - links
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    WebhookCreateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WebhookEnum'
        attributes:
          type: object
          properties:
            name:
              description: A name for the webhook.
              type: string
              example: My Webhook
            description:
              description: A description for the webhook.
              type: string
              example: A webhook for sms events
              nullable: true
            endpoint_url:
              description: A url to send webhook calls to. Must be https.
              type: string
              example: https://www.example.com/example/path
            secret_key:
              description: A secret key, that will be used for webhook request signing.
              type: string
              example: INSERT_SECRET_KEY
          required:
          - name
          - endpoint_url
          - secret_key
        relationships:
          type: object
          properties:
            webhook-topics:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    required:
                    - type
                    - id
                    properties:
                      type:
                        $ref: '#/components/schemas/WebhookTopicEnum'
                      id:
                        description: A list of topics to subscribe to.
                        type: string
                        example: event:klaviyo.sent_sms
          required:
          - webhook-topics
      required:
      - type
      - attributes
      - relationships
    WebhookEnum:
      type: string
      enum:
      - webhook
    ObjectLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
      required:
      - self
    CollectionLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        prev:
          type: string
          format: uri
        next:
          type: string
          format: uri
      required:
      - self
    GetWebhookTopicResponseCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WebhookTopicResponseObjectResource'
        links:
          $ref: '#/components/schemas/CollectionLinks'
      required:
      - data
    RelationshipLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        related:
          type: string
          format: uri
      required:
      - self
      - related
  responses:
    ClientError:
      description: Client Error
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - code
                  - title
                  - detail
                  properties:
                    id:
                      type: string
                    code:
                      type: string
                    title:
                      type: string
                    detail:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
                        parameter:
                          type: string
            required:
            - errors
    ServerError:
      description: Server Error
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - code
                  - title
                  - detail
                  properties:
                    id:
                      type: string
                    code:
                      type: string
                    title:
                      type: string
                    detail:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
                        parameter:
                          type: string
            required:
            - errors
  securitySchemes:
    Klaviyo-API-Key:
      type: apiKey
      in: header
      name: Authorization
      description: Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`<br>For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#authentication
      x-default: Klaviyo-API-Key your-private-api-key
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true