Skip to the content

Enable a disabled Webhook subscription

POST /v1/webhooks/{webhook_id}/enable

Property	Value
Operation	`enable_webhook`
Group	Webhooks
Scope	`webhooks:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `webhooks.subscription.enable` (mutation)
Released in	1.63.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Makes a disabled or paused subscription active again and answers it (1.63.0, FR-webhooks-8): its disabled reason clears, a new run of failures starts, and events created from now on are delivered; the deliveries that failed while it was disabled stay failed and replayable. An active subscription is answered unchanged.

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 POST "$VOCAL_API/v1/webhooks/whk_.../enable" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch(`${process.env.VOCAL_API}/v1/webhooks/whk_.../enable`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/webhooks/whk_.../enable",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
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.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

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`
`409`	`application/json`	ErrorEnvelope	`idempotency_in_progress`, `idempotency_key_reused`
`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`).