Squarespace Webhook Notification

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://developers.squarespace.com/schemas/squarespace/webhook-notification.json",
  "title": "Squarespace Webhook Notification",
  "description": "Represents the payload structure of a webhook notification sent by Squarespace when a subscribed event occurs on a merchant site. All notifications share a common envelope with a topic-specific data payload. Authenticity is verified via the Squarespace-Signature header using HMAC-SHA256.",
  "type": "object",
  "required": ["notificationId", "websiteId", "subscriptionId", "topic", "createdOn", "data"],
  "properties": {
    "notificationId": {
      "type": "string",
      "description": "Unique identifier for this specific notification delivery instance"
    },
    "websiteId": {
      "type": "string",
      "description": "Unique identifier of the Squarespace website that generated the event"
    },
    "subscriptionId": {
      "type": "string",
      "description": "Unique identifier of the webhook subscription that matched the 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 generated by Squarespace"
    },
    "data": {
      "description": "Topic-specific event data payload. Structure varies based on the topic value.",
      "oneOf": [
        { "$ref": "#/$defs/OrderCreateData" },
        { "$ref": "#/$defs/OrderUpdateData" },
        { "$ref": "#/$defs/ExtensionUninstallData" }
      ]
    }
  },
  "$defs": {
    "OrderCreateData": {
      "type": "object",
      "description": "Data payload for an order.create notification containing the ID of the newly created order",
      "required": ["orderId"],
      "properties": {
        "orderId": {
          "type": "string",
          "description": "Unique identifier of the newly created order. Use with the Orders API to retrieve full order details."
        }
      }
    },
    "OrderUpdateData": {
      "type": "object",
      "description": "Data payload for an order.update notification containing the updated order ID and description of the change",
      "required": ["orderId"],
      "properties": {
        "orderId": {
          "type": "string",
          "description": "Unique identifier of the order that was updated"
        },
        "orderUpdate": {
          "type": "string",
          "description": "Human-readable string describing what was updated on the order, such as fulfillment status changes"
        }
      }
    },
    "ExtensionUninstallData": {
      "type": "object",
      "description": "Data payload for an extension.uninstall notification",
      "properties": {
        "clientId": {
          "type": "string",
          "description": "The OAuth client ID of the Squarespace Extension that was uninstalled from the merchant site"
        }
      }
    },
    "WebhookSubscription": {
      "type": "object",
      "description": "A webhook subscription record configured via the Webhook Subscriptions API",
      "required": ["id", "endpointUrl", "topics"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the webhook subscription"
        },
        "endpointUrl": {
          "type": "string",
          "format": "uri",
          "description": "The publicly accessible HTTPS URL where notifications are delivered"
        },
        "topics": {
          "type": "array",
          "description": "List of event topics this subscription is configured to receive",
          "minItems": 1,
          "items": {
            "type": "string",
            "enum": ["order.create", "order.update", "extension.uninstall"]
          }
        },
        "secret": {
          "type": "string",
          "description": "HMAC-SHA256 signing secret returned only at creation or secret rotation. Must be stored securely."
        },
        "createdOn": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 UTC timestamp when the subscription was created"
        },
        "updatedOn": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 UTC timestamp when the subscription was last modified"
        }
      }
    }
  }
}