Skip to the content

Read a Webhook subscription

GET /v1/webhooks/{webhook_id}

Property	Value
Operation	`get_webhook`
Group	Webhooks
Scope	`webhooks:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A metadata read; a subscription and its deliveries hold URLs, ids, codes and measurements, never Call content.
Released in	1.63.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Answers one subscription and its revision as the ETag (1.63.0).

Request

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

curl "$VOCAL_API/v1/webhooks/whk_..." \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/webhooks/whk_...`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/webhooks/whk_...",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
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.

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`
`404`	`application/json`	ErrorEnvelope	`not_found`
`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`).