Skip to the content

Update a Webhook subscription

PATCH /v1/webhooks/{webhook_id}

Property	Value
Operation	`update_webhook`
Group	Webhooks
Scope	`webhooks:write`
Route class	`control`
Idempotency	No `Idempotency-Key`
Audit	Audited `webhooks.subscription.update` (mutation)
Released in	1.63.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Replaces the named fields at the revision If-Match names and answers the next revision (1.63.0), checked as a creation is on the merged subscription. A delivery already pending keeps the URL it was made for until its next attempt, which reads the subscription again.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the webhooks:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X PATCH "$VOCAL_API/v1/webhooks/whk_..." \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch(`${process.env.VOCAL_API}/v1/webhooks/whk_...`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'If-Match': '"1"',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());

import os

import requests

response = requests.patch(
    f"{os.environ['VOCAL_API']}/v1/webhooks/whk_...",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "If-Match": '"1"',
    },
    json={},
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`webhook_id`	path	WebhookId	yes	The id of a Webhook subscription: `whk_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`if-match`	header	string	yes	The revision the change was made against, quoted as the ETag returns it, or `*` to overwrite.

Request body

Content type application/json, required: WebhookSubscriptionUpdateRequest.

Field	Type	Required	Description
`compliance_policy_firings`	boolean	no	The opt-in to the record form of a compliance-tagged Policy firing, `policy.compliance_fired` (1.63.0): true delivers each to this subscription; false by default. From 1.64.0, stated: the subscription's event filter narrows it as it narrows every other type, since a filter the customer set holds.
`event_types`	array of EventTypeName	no
`families`	array of EventFamily	no
`filter_id`	EventFilterId or null	no
`include`	array of WebhookInclude	no
`purpose`	WebhookPurpose	no	`general` when omitted at creation.
`url`	string	no	The `https` URL deliveries are posted to, checked by the egress guard when saved and at every delivery (`egress_denied`).

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	WebhookSubscription
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`412`	`application/json`	ErrorEnvelope	`revision_mismatch`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`428`	`application/json`	ErrorEnvelope	`precondition_required`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is WebhookSubscription.

Field	Type	Required	Description
`api_version`	`"v1"`	yes	The envelope version, fixed at creation.
`compliance_policy_firings`	boolean	yes	The opt-in to the record form of a compliance-tagged Policy firing, `policy.compliance_fired` (1.63.0): true delivers each to this subscription; false by default. From 1.64.0, stated: the subscription's event filter narrows it as it narrows every other type, since a filter the customer set holds.
`created_at`	Timestamp	yes
`disabled_at`	Timestamp or null	yes
`disabled_reason`	WebhookDisabledReason or null	yes	Why the platform disabled it; null unless `disabled`.
`event_types`	array of EventTypeName	yes	The record types the subscription receives, beside its `families`.
`families`	array of EventFamily	yes	Whole families the subscription receives, beside `event_types`; at least one of the two is non-empty (1.52.0).
`filter_id`	EventFilterId or null	yes	The event filter that narrows the selection, or null (1.52.0).
`id`	WebhookId	yes
`include`	array of WebhookInclude	yes	Opt-in additions to a `post_call` delivery; empty for a `general` one (1.52.0).
`last_delivery`	WebhookLastDelivery or null	no	The newest delivery of the subscription, of any kind (1.64.0), so a list shows it without a read per subscription; null when the 30-day log holds none. Absent from an api older than 1.64.0.
`object`	`"webhook_subscription"`	yes
`previous_secret_expires_at`	Timestamp or null	yes	When the secret before the last rotation stops signing; null outside the window.
`purpose`	WebhookPurpose	yes
`revision`	integer	yes	Counts configuration writes; returned as the ETag and required in If-Match.
`secret_hint`	string	yes	The last four characters of the secret.
`status`	WebhookSubscriptionStatus	yes
`updated_at`	Timestamp	yes
`url`	string	yes	The `https` URL deliveries are posted to, checked by the egress guard when saved and at every delivery (`egress_denied`).