Create a webhook subscription

Creates a subscription that POSTs a signed event envelope to a public HTTPS URL for each matching event type (or ["*"] for all). The response returns the whsec_ signing secret ONCE; no other response contains it, so store it then. Idempotency-Key is required, and a replayed response carries the secret again with Cache-Control: no-store. A company can hold at most 20 subscriptions. Every delivery is signed with Cybooks-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + raw body)>; see the Webhooks guide. Requires the webhooks:write OAuth scope. The credential's user needs the manage_integrations permission.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Fields accepted to create a webhook subscription. The schema identifies required and optional values.

POST /v1/webhook-subscriptions — and, through
{@see UpdateWebhookSubscriptionApiRequest}, the sparse PATCH contract.

event_types is a non-empty list of exact catalog types, or exactly
["*"] for every current and future type (preview included). There are no
family wildcards, and webhook_subscription.tested is never subscribable.
The destination URL is checked syntactically AND resolved by the
application service ({@see \App\Core\PublicApi\Webhooks\PublicApiWebhookDestinationGuard}),
which answers with its own stable 422 codes.

string
required
length ≤ 2048
string | null
string
enum
Allowed:
event_types
array of strings
required
length between 1 and 300
event_types*
Headers
string
required
length ≤ 191

Required unique key whose request hash and terminal response are stored durably for 24 hours.

Responses

Language
Credentials
OAuth2
Missing 1 required scope
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
*/*