---
title: "Create webhook subscription"
method: POST
path: "/1.0/webhook_subscriptions"
tags: ["WebhookSubscriptions"]
---

# Create webhook subscription

`POST /1.0/webhook_subscriptions`

## Request

- Base URL: `https://api.squarespace.com`
- URL: `https://api.squarespace.com/1.0/webhook_subscriptions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/squarespace/apis/commerce-api/docs/1.0/webhook_subscriptions/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a webhook subscription. A successful request returns the created Webhook Subscription resource. Requires an OAuth access token; API keys are not supported. The OAuth token must hold scopes appropriate for each subscribed event topic: order.create and order.update require website.orders or website.orders.read; contact.create, contact.update, contact.delete, address.create, address.update, and address.delete require website.contacts; extension.uninstall requires no event-specific scope.

## Headers

- `Authorization` string, required
- `User-Agent` string, required

## Request body

- ExternalCreateWebhookSubscriptionRequest
  - `endpointUrl` string, required: HTTPS URL to POST webhook notifications.
  - `topics` string[]: List of event topics that trigger a webhook notification.

## Response `201`

The created webhook subscription.

- ExternalCreateWebhookSubscriptionResponse
  - `clientId` string, required: Third-party client id.
  - `createdOn` string, date-time, required: ISO 8601 UTC date and time string; represents when the webhook subscription was created.
  - `endpointUrl` string, required: HTTPS URL to POST webhook notifications.
  - `id` string, required: Unique Webhook Subscription id.
  - `secret` string, required: Hexadecimal value used to generate a signature for a webhook notification; field is only returned when creating a new subscription or rotating a secret. Store the secret in a safe location to verify notifications from Squarespace. See the 'Verifying notifications' guide under Webhooks for details.
  - `topics` string[]: List of event topics that trigger a webhook notification.
  - `updatedOn` string, date-time, required: ISO 8601 UTC date and time string; represents when the webhook subscription was last modified.
  - `websiteId` string, required: Unique Webhook Subscription id.

## Other responses

- `400`: Invalid input or malformed JSON
- `404`: Not found. The API version is not supported.
- `409`: The Squarespace website has reached its limit of 25 webhook subscriptions.

---

[API](https://skmtc.dev/squarespace/apis/commerce-api.md) - [All operations](https://skmtc.dev/squarespace/apis/commerce-api/llms.txt) - [OpenAPI document](https://skmtc.dev/squarespace/apis/commerce-api/revisions/5dd4b1b7cd38?raw)