Skip to main content
PUT
Update a subscription

Authorizations

Authorization
string
header
required

API key passed as a Bearer token in the Authorization header: Authorization: Bearer <YOUR_API_KEY>.

Path Parameters

id
string
required

The subscription ID.

Body

application/json
name
string
required

Display name for the subscription (non-blank; unique per organization).

Example:

"Payment Events Webhook"

active
boolean
required

Whether deliveries are attempted (true) or paused (false).

Example:

true

url
string

Destination endpoint that receives event POSTs. Must match ^https?://.*. Required for PUSH; must be omitted for PULL.

Pattern: ^https?://.*
Example:

"https://api.example.com/webhooks/payments"

delivery_mode
enum<string>
default:PUSH

How events are delivered. PUSH (default) sends HTTP POSTs to url. PULL stores events for you to fetch with the pull API: url must be omitted and signing is not supported. Omitting it on update sets the subscription to PUSH.

Available options:
PUSH,
PULL
enable_signed_webhooks
boolean

HMAC signing toggle for PUSH subscriptions. Optional: omitted means false (unsigned). On create, true generates a whsec_ signing secret returned once in the response. On update, true enables signing on an unsigned subscription (new secret returned once) and is a no-op when already signed; false disables signing and permanently clears the secret. Not supported for PULL (true returns 400).

Example:

true

events
string[]

Event types to subscribe to, each in the case-sensitive Service.Event pattern (e.g. CallHandler.CallStarted). Every event must exist in the event-type catalog, otherwise 400. An empty array or ["*"] subscribes to all events.

Example:
headers
Headers · object

Custom HTTP headers sent with each delivery (string->string map; e.g. auth tokens for your receiving endpoint).

Example:
description
string

Free-text description (max 1500 chars).

Maximum string length: 1500
Example:

"Receives payment events with custom authentication"

agent_ids
string[]

Scope the subscription to specific agents (scope = AGENT).

workspace_ids
string[]

Scope the subscription to specific workspaces (scope = WORKSPACE).

request_timeout_ms
integer
default:1000

Per-attempt delivery timeout in milliseconds (1000-3000).

Required range: 1000 <= x <= 3000
retry_policy
WebhookRetryPolicy · object

Delivery retry policy. Defaults to FIXED_DELAY with 3 attempts.

Example:

Response

OK. Includes a new secret only if this update just enabled signing.

id
string

Subscription ID. Required for GET / PUT / DELETE.

Example:

"6a27a76692d9e3a8ffd7e62d"

organization_id
string

Owning organization (resolved from your API key).

Example:

"ddd6f1d8-b232-497e-bf1e-ea7317622d17"

scope
enum<string>

Resolved delivery scope.

Available options:
ORGANIZATION,
WORKSPACE,
AGENT
Example:

"ORGANIZATION"

created_user_id
string

User that created the subscription.

Example:

"google-oauth2|101090478854418701727"

name
string
Example:

"Payment Events Webhook"

url
string
Example:

"https://api.example.com/webhooks/payments"

events
string[]
Example:
active
boolean
Example:

true

delivery_mode
enum<string>

How the subscription receives events: PUSH (HTTP delivery) or PULL (fetched via the pull API).

Available options:
PUSH,
PULL
Example:

"PUSH"

headers
Headers · object

Custom HTTP headers forwarded with each delivery; omitted when unset.

Example:
description
string

Free-text description; omitted when unset.

Example:

"Receives payment events with custom authentication"

agent_ids
string[]

Agent scope; omitted when unset.

workspace_ids
string[]

Workspace scope; omitted when unset.

request_timeout_ms
integer

Per-attempt delivery timeout in ms (default 1000).

Example:

1000

retry_policy
WebhookRetryPolicy · object

Delivery retry configuration. retryStrategy selects the strategy. When omitted, a FIXED_DELAY policy with 3 attempts is used.

Example:
signing_enabled
boolean

Whether the subscription has a signing secret. Always present.

Example:

true

secret
string

HMAC signing secret, prefixed whsec_. Present only at issuance when signing is enabled. Never returned by read endpoints.

Example:

"whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

previous_secret
string

Previous signing secret, kept for up to 72 hours after a rotation so deliveries are dual-signed. Omitted otherwise.

previous_secret_expires_at
string<date-time>

When the previous secret stops being used. Omitted outside a rotation grace window.

created_at
string<date-time>
Example:

"2026-06-09T10:15:00.000Z"

updated_at
string<date-time>
Example:

"2026-06-09T10:15:00.000Z"