v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
Webhooks

Update webhook

Update an existing webhook configuration. All fields except _id are optional; only provided fields will be updated.

When provided, name must be 1-50 characters, url must be a valid URL, and events must contain at least one event. Whitespace is trimmed from url before validation.

Webhooks are automatically disabled after 10 consecutive delivery failures.

A restricted (zrk_) API key can only set events to events whose resource group the key holds; an event outside the key's groups is rejected with 403. It also cannot widen an existing subscription past its own groups.

disabledResourceGroups replaces the subscription's own denylist, which applies to delivery regardless of which key or session created it. Send an empty array to clear it. A restricted key's own disabled groups are unioned into the stored value on every update, so repointing a legacy unrestricted subscription with a restricted key also narrows it.

Timing: the new denylist applies to every event emitted after the update. Events already queued for delivery when the update landed were filtered against the previous denylist and can still arrive at your endpoint for up to five minutes after they were enqueued, because the delivery worker trusts a five-minute enqueue-time snapshot before re-checking the subscription. Retries beyond that window, dead-letter replays, test fires, and redeliveries are all checked against the current denylist.

put/v1/webhooks/settings

Request body

_idstring required

Webhook ID to update (required)

namestring

Webhook name (1-50 characters). Must be non-empty if provided.

urlstring uri

Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided.

secretstring

Secret key for HMAC-SHA256 signature verification

eventsstring[]

Events to subscribe to. Must contain at least one event if provided.

isActiveboolean

Enable or disable webhook delivery

customHeadersobject

Custom headers to include in webhook requests

disabledResourceGroupsstring[]

Replaces the subscription's denylist. Send an empty array to clear it and receive every event in events again. Omitting the field leaves the current denylist untouched. Applies to events emitted after the update; already-queued events can still deliver for up to five minutes after they were enqueued. When the caller is a restricted (zrk_) key, that key's own disabled groups are unioned back in either way, so a restricted key can neither clear nor widen a subscription past its own groups.

Response

Webhook updated successfully

successboolean