The Squarespace Webhook Subscriptions API allows developers to manage webhook endpoint subscriptions for a merchant site. It supports creating, listing, updating, and deleting subscriptions that trigger notifications for order events, extension uninstalls, and other commerce activities.
openapi: 3.1.0
info:
title: Squarespace Commerce Inventory Webhook Subscriptions API
description: The Squarespace Commerce API provides programmatic access to the commerce features of a Squarespace merchant site. It enables developers to build integrations and applications that manage products, process orders, track inventory, access customer profiles, retrieve financial transactions, and configure webhook subscriptions. All endpoints use HTTPS and follow REST principles with standard verbs and response status codes. Authentication is handled via API keys or OAuth tokens.
version: '1.0'
contact:
name: Squarespace Developer Support
url: https://developers.squarespace.com/commerce-apis/overview
termsOfService: https://www.squarespace.com/terms-of-service
servers:
- url: https://api.squarespace.com/1.0
description: Production Server
security:
- bearerAuth: []
tags:
- name: Webhook Subscriptions
description: Manage webhook subscriptions for real-time event notifications
paths:
/webhook_subscriptions:
get:
operationId: listWebhookSubscriptions
summary: Retrieve All Webhook Subscriptions
description: Returns all webhook subscriptions configured for the authenticated merchant site. Each subscription includes its endpoint URL, subscribed topics, and creation metadata. Squarespace supports up to 25 active webhook subscriptions per website.
tags:
- Webhook Subscriptions
responses:
'200':
description: Successful response with list of webhook subscriptions
content:
application/json:
schema:
type: object
properties:
webhookSubscriptions:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createWebhookSubscription
summary: Create a Webhook Subscription
description: Creates a new webhook subscription for the authenticated merchant site. The subscription must specify a publicly accessible endpoint URL and at least one event topic to subscribe to. Upon creation, a secret is generated for verifying the authenticity of incoming webhook notifications via HMAC-SHA256 signature validation. Requires OAuth token authentication.
tags:
- Webhook Subscriptions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookSubscriptionRequest'
responses:
'200':
description: Webhook subscription created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptionWithSecret'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/webhook_subscriptions/{subscriptionId}:
get:
operationId: getWebhookSubscription
summary: Retrieve a Specific Webhook Subscription
description: Retrieves details for a single webhook subscription by its unique identifier. Returns the subscription configuration including endpoint URL and subscribed topics. The subscription secret is not returned in this response.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionId'
responses:
'200':
description: Successful response with webhook subscription details
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: updateWebhookSubscription
summary: Update a Webhook Subscription
description: Updates an existing webhook subscription. The endpoint URL and subscribed topics can be modified. Requires OAuth token authentication.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookSubscriptionRequest'
responses:
'200':
description: Webhook subscription updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscription'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteWebhookSubscription
summary: Delete a Webhook Subscription
description: Permanently deletes a webhook subscription. After deletion, Squarespace will no longer send event notifications to the subscription's endpoint URL. Requires OAuth token authentication.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionId'
responses:
'204':
description: Webhook subscription deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/webhook_subscriptions/{subscriptionId}/actions/sendTestNotification:
post:
operationId: sendTestNotification
summary: Send a Test Notification
description: Sends a test notification to the webhook subscription's configured endpoint URL. This is useful for verifying that the endpoint is reachable and correctly processing Squarespace webhook payloads before relying on live events.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionId'
responses:
'200':
description: Test notification sent successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/webhook_subscriptions/{subscriptionId}/actions/rotateSecret:
post:
operationId: rotateWebhookSecret
summary: Rotate a Webhook Subscription Secret
description: Generates a new secret for the specified webhook subscription and invalidates the previous secret. The new secret must be stored securely and used to verify the Squarespace-Signature header on subsequent notifications. Rotating the secret is recommended periodically or when the secret may have been compromised.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/subscriptionId'
responses:
'200':
description: Webhook secret rotated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptionWithSecret'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
Error:
type: object
description: Standard error response returned by the Squarespace API
properties:
type:
type: string
description: Machine-readable error type identifier
subtype:
type: string
description: Optional more specific error subtype
message:
type: string
description: Human-readable description of the error
statusCode:
type: integer
description: HTTP status code associated with the error
WebhookSubscriptionWithSecret:
allOf:
- $ref: '#/components/schemas/WebhookSubscription'
- type: object
properties:
secret:
type: string
description: The HMAC-SHA256 signing secret used to verify the Squarespace-Signature header on incoming notifications. Only returned on creation and secret rotation. Store this value securely as it cannot be retrieved again.
UpdateWebhookSubscriptionRequest:
type: object
description: Request body for updating an existing webhook subscription
properties:
endpointUrl:
type: string
format: uri
description: Updated HTTPS URL to receive event notification payloads
topics:
type: array
description: Updated list of event topics to subscribe to
minItems: 1
items:
type: string
enum:
- order.create
- order.update
- extension.uninstall
CreateWebhookSubscriptionRequest:
type: object
description: Request body for creating a new webhook subscription
required:
- endpointUrl
- topics
properties:
endpointUrl:
type: string
format: uri
description: The publicly accessible HTTPS URL to receive event notification payloads
topics:
type: array
description: List of event topics to subscribe to. Must include at least one topic.
minItems: 1
items:
type: string
enum:
- order.create
- order.update
- extension.uninstall
WebhookSubscription:
type: object
description: A webhook subscription configuration for receiving event notifications
properties:
id:
type: string
description: Unique identifier for the webhook subscription
endpointUrl:
type: string
format: uri
description: The URL to which Squarespace sends event notification payloads. Must be a publicly accessible HTTPS endpoint.
topics:
type: array
description: List of event topics this subscription is configured to receive
items:
type: string
enum:
- order.create
- order.update
- extension.uninstall
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 updated
parameters:
subscriptionId:
name: subscriptionId
in: path
description: The unique identifier of the webhook subscription
required: true
schema:
type: string
responses:
Unauthorized:
description: Authentication credentials are missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The request was malformed or contained invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The authenticated user does not have permission to access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Authenticate using an API key or OAuth access token. Include the token in the Authorization header as "Bearer YOUR_TOKEN".
externalDocs:
description: Squarespace Commerce API Documentation
url: https://developers.squarespace.com/commerce-apis/overview