Create a webhook subscription

post /api/webhook_subscriptions

Creates a WebhookSubscription resource.

Subscribes a callbackUrl (an HTTPS endpoint) to a webhook topic. topic, callbackUrl and version are required: pin the version of the delivered payload (such as 2026-07) so its shape never changes without you asking. Optionally narrow the payload with includeFields. Requires the webhooks:write and webhooks:read scopes.

Store the secret

The creation response is the only one that returns the signing secret. Store it right away: it is never returned again.

Request body

Property	Type	Required	Description
callbackUrl	string | null	required
includeFields	array | null	-	Dot-path field selection limiting the delivered payload. Null or empty means the full payload. A * segment is a wildcard (e.g. *.id); the resource id is always included.
topic	"product/created" | "product/updated" | "product/deleted"	required
version	string | null	required	The API version of the delivered payload (e.g. 2026-07 or unstable). Required: pin it explicitly so the shape you receive never changes without you asking.

Response

201 - WebhookSubscription resource created

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
callbackUrl	string | null	-	The HTTPS endpoint notified when the topic fires.
createdAt	string	-
id	string	-
includeFields	array | null	-	Dot-path field selection limiting the delivered payload. Null or empty means the full payload. A * segment is a wildcard (e.g. *.id); the resource id is always included.
secret	string | null	-	The signing secret. Returned only once, in the creation response.
topic	string | null	-	The event topic to subscribe to.
updatedAt	string	-
version	string | null	-	The pinned payload API version, or null when dynamic.

Errors

400 - Invalid input

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
code	string	-	Stable identifier of the error in the error code catalogue (see /api/error-codes). Present on catalogued errors only.
description	string | null	-
detail	string | null	-	A human-readable explanation specific to this occurrence of the problem.
instance	string | null	-	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
message	string	-	End-user message localized in the request locale, with this occurrence's values substituted. Present on catalogued errors only.
slug	string	-	Stable, readable key of the error in the error code catalogue. Present on catalogued errors only.
status	integer | null	-
title	string | null	-	A short, human-readable summary of the problem. For a catalogued error it repeats the slug.
type	string	-	A URI reference that identifies the problem type. For a catalogued error it is the error code resource, /api/error-codes/{code}.

403 - Access denied. The caller is missing one or more permissions required for this operation.

Content-Type: application/problem+json

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
detail	string	-
missingPermissions	string[]	-	Permissions that the caller is missing for this operation. Present only when the 403 is caused by a denied permission.
status	integer	-
title	string	-
type	string	-

422 - An error occurred

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
description	string	-
detail	string	-
instance	string | null	-
status	integer	-
title	string | null	-
type	string	-
violations	object[]	-
Show violations fields Property Type Required Description code string - The code of the violation hint string - An extra hint to understand the violation message string required The message associated with the violation parameters object - Dynamic placeholder values for the violation message template (substitute into the code catalogue message). payload object - The serialized payload of the violation propertyPath string required The property path of the violation slug string - Stable centralized error-code slug for this violation (see /api/error-codes).