v2

latestOpenAPI 3.1.02026-08-075421692.0 MB

Webhooks

Create webhook

Create a new webhook configuration. Maximum 50 webhooks per user.

name, url and events are required. 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 subscribe to events whose resource group the key holds; an event outside the key's groups is rejected with 403, so a restricted key can never create a subscription broader than itself.

disabledResourceGroups restricts the subscription itself, independently of which key or session later reads it. Events in a disabled group are dropped before delivery to this endpoint, on live delivery and on every replay path (test fire, redelivery, dead-letter requeue), even if they are listed in events. Omit it to receive everything in events, which is how existing subscriptions behave. A restricted key's own disabled groups are always unioned in.

post/v1/webhooks/settings

Request body

namestring required

Webhook name (1-50 characters)

urlstring uri required

Webhook endpoint URL (must be a valid URL, whitespace trimmed)

secretstring

Secret key for HMAC-SHA256 signature verification

eventsstring[] required

Events to subscribe to (at least one required)

isActiveboolean

Enable or disable webhook delivery. Defaults to true when omitted.

customHeadersobject

Custom headers to include in webhook requests

disabledResourceGroupsstring[]

Resource groups this subscription does not receive (opt-out denylist). Omit or send an empty array to receive every event in events. Listing a group here drops its events before delivery and on every replay path. Set at creation it applies to everything this subscription ever receives; changed later via PUT it applies to events emitted after the change, with a five-minute tail for events already queued (see that operation). When the caller is a restricted (zrk_) key, that key's own disabled groups are unioned into whatever you send here, so a restricted key can never create a subscription wider than itself.

Response

Webhook created successfully

successboolean