Squarespace Webhook Events

asyncapi: 2.6.0
info:
  title: Squarespace Webhook Events
  description: >-
    The Squarespace webhook system delivers real-time event notifications to
    registered endpoint URLs when commerce activity occurs on a merchant site.
    Supported events include order creation, order updates, and extension uninstalls.
    Each notification includes a unique identifier, the website ID, subscription ID,
    topic, and a data payload specific to the event type. Notifications are signed
    using HMAC-SHA256 with the subscription secret, enabling receivers to verify
    authenticity via the Squarespace-Signature header.
  version: '1.0'
  contact:
    name: Squarespace Developer Support
    url: https://developers.squarespace.com/webhooks/overview
  termsOfService: https://www.squarespace.com/terms-of-service
externalDocs:
  description: Squarespace Webhooks Documentation
  url: https://developers.squarespace.com/webhooks/overview
servers:
  squarespace:
    url: 'https://api.squarespace.com'
    protocol: https
    description: >-
      Squarespace sends webhook notifications as HTTP POST requests from this
      origin. Receiving endpoints must be publicly accessible HTTPS URLs registered
      via the Webhook Subscriptions API.
    security:
      - hmacSignature: []
channels:
  /webhook:
    description: >-
      The endpoint on the subscriber's server that receives webhook notifications
      from Squarespace. Squarespace sends HTTP POST requests with JSON payloads
      and a Squarespace-Signature header for verification.
    publish:
      operationId: receiveWebhookNotification
      summary: Receive a webhook notification from Squarespace
      description: >-
        Squarespace sends this message to the subscriber's registered endpoint URL
        when a subscribed event occurs on the merchant site. The receiver should
        validate the Squarespace-Signature header before processing the payload.
        Squarespace expects a 2xx response within a short timeout window.
      message:
        oneOf:
          - $ref: '#/components/messages/OrderCreateNotification'
          - $ref: '#/components/messages/OrderUpdateNotification'
          - $ref: '#/components/messages/ExtensionUninstallNotification'
components:
  securitySchemes:
    hmacSignature:
      type: httpApiKey
      name: Squarespace-Signature
      in: header
      description: >-
        HMAC-SHA256 signature generated by signing the raw request body with the
        webhook subscription secret as the key. Recipients must compute the same
        signature and compare it to the header value to verify the notification
        originated from Squarespace.
  messages:
    OrderCreateNotification:
      name: order.create
      title: Order Create Notification
      summary: Notification sent when a new order is created on the merchant site
      description: >-
        Squarespace sends this notification when a customer places a new order on
        the merchant site. The data payload contains the unique order ID. Use the
        Orders API to retrieve full order details using this ID.
      contentType: application/json
      headers:
        type: object
        properties:
          Squarespace-Signature:
            type: string
            description: >-
              HMAC-SHA256 signature of the request body using the subscription
              secret as the key. Used to verify notification authenticity.
      payload:
        $ref: '#/components/schemas/OrderCreatePayload'
    OrderUpdateNotification:
      name: order.update
      title: Order Update Notification
      summary: Notification sent when an existing order is updated on the merchant site
      description: >-
        Squarespace sends this notification when an order is modified, such as when
        fulfillment status changes or the order is refunded. The data payload contains
        the order ID and an update type description.
      contentType: application/json
      headers:
        type: object
        properties:
          Squarespace-Signature:
            type: string
            description: >-
              HMAC-SHA256 signature of the request body using the subscription
              secret as the key. Used to verify notification authenticity.
      payload:
        $ref: '#/components/schemas/OrderUpdatePayload'
    ExtensionUninstallNotification:
      name: extension.uninstall
      title: Extension Uninstall Notification
      summary: Notification sent when a Squarespace Extension is uninstalled from a site
      description: >-
        Squarespace sends this notification when a merchant uninstalls a Squarespace
        Extension. Receiving this event should trigger cleanup of any stored data
        or active resources associated with the merchant's site in the extension's
        backend systems.
      contentType: application/json
      headers:
        type: object
        properties:
          Squarespace-Signature:
            type: string
            description: >-
              HMAC-SHA256 signature of the request body using the subscription
              secret as the key. Used to verify notification authenticity.
      payload:
        $ref: '#/components/schemas/ExtensionUninstallPayload'
  schemas:
    NotificationBase:
      type: object
      description: Common fields present in all Squarespace webhook notification payloads
      required:
        - notificationId
        - websiteId
        - subscriptionId
        - topic
        - createdOn
      properties:
        notificationId:
          type: string
          description: Unique identifier for this specific notification delivery
        websiteId:
          type: string
          description: >-
            Unique identifier of the Squarespace website that triggered the
            notification
        subscriptionId:
          type: string
          description: Unique identifier of the webhook subscription that received this event
        topic:
          type: string
          description: The event topic that triggered this notification
          enum:
            - order.create
            - order.update
            - extension.uninstall
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the notification was created
    OrderCreatePayload:
      allOf:
        - $ref: '#/components/schemas/NotificationBase'
        - type: object
          description: Payload for an order.create webhook notification
          required:
            - data
          properties:
            topic:
              type: string
              enum:
                - order.create
            data:
              type: object
              description: Data payload for the order create event
              required:
                - orderId
              properties:
                orderId:
                  type: string
                  description: >-
                    Unique identifier of the newly created order. Use this ID with
                    the Orders API to retrieve full order details.
    OrderUpdatePayload:
      allOf:
        - $ref: '#/components/schemas/NotificationBase'
        - type: object
          description: Payload for an order.update webhook notification
          required:
            - data
          properties:
            topic:
              type: string
              enum:
                - order.update
            data:
              type: object
              description: Data payload for the order update event
              required:
                - orderId
              properties:
                orderId:
                  type: string
                  description: >-
                    Unique identifier of the updated order. Use this ID with the
                    Orders API to retrieve the current order state.
                orderUpdate:
                  type: string
                  description: >-
                    A string describing the type of update that was made to the
                    order, such as fulfillment status changes or refunds.
    ExtensionUninstallPayload:
      allOf:
        - $ref: '#/components/schemas/NotificationBase'
        - type: object
          description: Payload for an extension.uninstall webhook notification
          required:
            - data
          properties:
            topic:
              type: string
              enum:
                - extension.uninstall
            data:
              type: object
              description: Data payload for the extension uninstall event
              properties:
                clientId:
                  type: string
                  description: The client ID of the extension that was uninstalled