---
title: "Update webhook"
method: PUT
path: "/v1/webhooks/settings"
tags: ["Webhooks"]
---

# Update webhook

`PUT /v1/webhooks/settings`

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.

## Request body

- object
  - `_id` string, required — Webhook ID to update (required)
  - `name` string — Webhook name (1-50 characters). Must be non-empty if provided.
  - `url` string, uri — Webhook endpoint URL (must be a valid URL, whitespace trimmed). Must be a valid URL if provided.
  - `secret` string — Secret key for HMAC-SHA256 signature verification
  - `events` string[] — Events to subscribe to. Must contain at least one event if provided.
  - `isActive` boolean — Enable or disable webhook delivery
  - `customHeaders` object — Custom headers to include in webhook requests
  - `disabledResourceGroups` string[] — 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 `200`

Webhook updated successfully

- object
  - `success` boolean
  - `webhook` Webhook — Individual webhook configuration for receiving real-time notifications
    - `_id` string — Unique webhook identifier
    - `name` string — Webhook name (for identification)
    - `url` string, uri — Webhook endpoint URL
    - `secret` string — Secret key for HMAC-SHA256 signature verification.
    - `events` string[] — Events subscribed to
    - `isActive` boolean — Whether webhook delivery is enabled
    - `lastFiredAt` string, date-time — Timestamp of last successful webhook delivery
    - `failureCount` integer — Consecutive delivery failures (resets on success, webhook disabled at 10)
    - `customHeaders` object — Custom headers included in webhook requests
    - `disabledResourceGroups` string[] — Resource groups this subscription does not receive (opt-out denylist, same vocabulary and same semantics as the field on API keys). Absent or empty means the subscription receives every event listed in `events`, which is how every subscription created before this field existed behaves. An event whose group is listed here is dropped before delivery even when it is still present in `events`, and the same check runs on every replay path (test fire, redelivery, dead-letter requeue). Editing the denylist applies to every event emitted afterwards; events already queued when the edit landed can still be delivered for up to five minutes after they were enqueued.

## Other responses

- `400` — Validation error or missing webhook ID
- `401` — Unauthorized
- `403` — The API key is a restricted key (zrk_ prefix) and may not perform this operation. Three cases. (1) The operation's resource group (see the operation's x-resource-group) is disabled on the key: fix it by creating a key with the group enabled in the dashboard API keys tab and revoking the old one. (2) The operation is admin-plane (x-resource-group admin-plane: API keys, invites, connected apps, member identity), which is never grantable to restricted keys; the error reads "Restricted API keys cannot manage API keys, invites, or member identity." and the fix is a full-access key or the dashboard, never a new restricted key. (3) On webhook subscription writes, delivery-log reads and replays, a named event maps to a resource group the key does not hold, so a restricted key can never create or edit a subscription broader than itself (a no-messages key cannot subscribe to, test-fire, redeliver or read logs for message.* events).
- `404` — Webhook not found

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)