Update webhook subscription
Creates or updates the webhook endpoint URL, enabled state, and subscribed event types.
Enabling the webhook automatically provisions a signing secret if one does not exist.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Create or update your webhook subscription: the endpoint URL that receives events, whether delivery is enabled, and which event types you subscribe to. Enabling the webhook automatically provisions a signing secret if one does not already exist. Returns the current subscription, identical to the payload from GET /webhooks/subscription.
Authentication & access
- Requires the
webhooks.subscription.writepermission. - Allowed roles: OWNER or DEVELOPER.
- When called with a dashboard account token (rather than an API token), this is a sensitive action: the account must complete step-up verification and send the
X-Security-Token,X-Security-Code, andX-Security-Methodheaders. Missing or invalid verification is rejected (403/400).
Request body
All fields are optional, and only the fields you send are applied (partial update).
| Field | Type | Notes |
|---|---|---|
webhook_url | string | null | HTTPS endpoint that receives events (max 1024 chars). Send null to clear it. The URL must use https, contain no embedded credentials, and resolve to a public host (loopback, private, link-local, and internal hostnames are rejected). |
webhook_enabled | boolean | null | Turn delivery on or off. |
webhook_events | array of string | null | Event types to subscribe to. Each must be a supported event type (see GET /webhooks/events); unknown types and empty lists are rejected. Duplicates are de-duplicated. |
When webhook_enabled is set to true:
- A non-empty
webhook_urlmust be configured, otherwise the request is rejected (400). - If no events are selected, the subscription defaults to all supported event types.
- A signing secret is provisioned automatically if one is not already set.
Response
200 with the current subscription: webhook_url, webhook_enabled, webhook_events, has_signing_secret, webhook_secret_kid, webhook_secret_rotated_at, and webhook_updated_at. The signing secret value itself is never returned here; it is shown only once when rotated via POST /webhooks/subscription/rotate-secret.
Error responses
| Status | When |
|---|---|
400 | webhook_url is not HTTPS, empty, malformed, contains credentials, or resolves to a blocked/unresolvable host; an unsupported or empty webhook_events list; webhook_enabled is true but no webhook_url is configured; invalid or expired step-up security challenge (dashboard account tokens) |
403 | Step-up verification required but missing/mismatched (dashboard account tokens): missing security headers, non-dashboard token, or a challenge that does not match this operation |
404 | The authenticated client record was not found |
422 | Request body failed validation |
Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.