Update webhook endpoint | SpeechifyAI API

curl -X PATCH https://api.speechify.ai/v1/webhooks/endpoints/whe_01jqr8x9zg5k2m3n4p5q6r7s8t \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://example.com/webhook",
  "enabled_events": [
    "example"
  ],
  "description": "Example description.",
  "disabled": false
}'

{
  "id": "whe_01kwxwcbyb6wk952swa0432cf1",
  "url": "https://example.com/speechify/webhooks",
  "enabled_events": [
    "conversation.completed"
  ],
  "include": [
    "messages"
  ],
  "api_version": "2026-06-28",
  "disabled": false,
  "created_at": "2026-06-24T18:03:11Z",
  "updated_at": "2026-06-24T18:03:11Z",
  "description": "Example description.",
  "secret": "whsec_demo••••0000"
}

Partial update; omitted fields are left unchanged. Set disabled to pause delivery without deleting the endpoint.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

webhook_endpoint_idstringRequired

Webhook endpoint id (prefixed whe_…).

Request

This endpoint expects an object.

urlstringOptionalformat: "uri"

HTTPS destination for event deliveries. Must be a publicly reachable host: loopback, private, link-local, and cloud-metadata addresses (and reserved hostnames like localhost) are rejected.

project_idstring or nullOptional

Re-scope the endpoint: a proj_... id narrows it to that project’s events, an explicit null makes it workspace-wide (every project’s events), omitted leaves it unchanged. The signing secret and delivery history are untouched, so re-scoping never requires redeploying your receiver. An unknown id returns 404 project_not_found. A project-pinned API key may only scope an endpoint to its own project.

enabled_eventslist of stringsOptional

includelist of stringsOptional

Payload-shaping keys (see WebhookEndpoint.include). Send [] to clear back to the lean default.

api_versiondateOptional

Opt the endpoint into a different (typically newer) payload shape (YYYY-MM-DD, see WebhookEndpoint.api_version). Omit to leave it unchanged. An unknown version is rejected.

descriptionstring or nullOptional

disabledbooleanOptional

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The updated endpoint (without the signing secret).

idstringformat: "^whe_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire id (whe_<26 char Crockford base32>).

urlstringformat: "uri"

HTTPS destination Speechify POSTs signed events to.

enabled_eventslist of strings

The events this endpoint receives: a list of catalog event names (see WebhookEventType) or ["*"] for every event, current and future.

includelist of strings

Per-event payload shaping. Deliveries are lean by default: data.object carries only the resource GET snapshot. List heavy collections here to have them appended under the event’s data alongside object, so receivers behind hard request-size caps stay lean unless they opt in. Recognised keys (conversation events only): messages (the full transcript) and evaluations. Empty = lean.

api_versiondate

The dated payload shape this endpoint receives (YYYY-MM-DD), the same versioning vocabulary the REST API uses. Every delivery is rendered back to this version and carries it in the Speechify-Version header and the payload’s top-level version field. Defaults to your workspace’s current version at creation; change it to opt into a newer shape.

disabledboolean

When true, Speechify stops delivering to this endpoint.

created_atdatetime

updated_atdatetime

project_idstring or nullOptionalformat: "^proj_[0-9a-hjkmnp-tv-z]{26}$"

The project whose events this endpoint receives (prefixed external id). Null means workspace-wide - it receives every project’s events. Endpoints have no Default project.

descriptionstring or nullOptional

Optional human-readable label for the endpoint.

secretstringOptional

The HMAC-SHA256 signing secret (whsec_…) used to verify the Speechify-Signature header. Returned ONLY when the endpoint is created or its secret is rotated — it is never shown again.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error