Skip to main content

Create Webhook Subscription

POST 
/api/webhook-subscriptions

Create a subscription. Body fields:

Required scope: webhooks:manage

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

  • event (required, string) — wire event name; must be one of the catalog events (see List Events). The token must also hold that event's READ scope.
  • target_url (required, string, max 2048, valid URL) — endpoint to receive deliveries. Must start with https:// and must pass the SSRF guard: the host has to resolve, and no resolved address may fall in a loopback, link-local, private or otherwise reserved range.

The signing secret is returned in the response exactly once and is never retrievable again — store it immediately.

(event, target_url) is unique per tenant. A duplicate POST returns 409 Conflict carrying existing_subscription_id so the client can open the subscription that already exists; it never creates a second row and never issues a second secret. Disabled subscriptions count as duplicates — re-enable the existing one (see Enable Webhook Subscription) instead of creating another, or two identical rows would double every delivery once the first is turned back on.

Validation failures return 422 with per-field errors, each entry carrying message, code and data. A target URL that fails the SSRF guard also returns 422, reported against the target_url field so the form can mark the input.

Requires the webhooks:manage scope, plus the event's own READ scope.

Request​

Responses​

Created

Response Headers
    Content-Type