API ReferenceWebhooks

Get webhook endpoint

Beta
Fetch a webhook endpoint by id. The signing secret is never returned.

Authentication

AuthorizationBearer

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

Path parameters

webhook_endpoint_idstringRequired

Webhook endpoint id (prefixed whe_…).

Headers

Speechify-VersionstringOptional

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).

Response

The webhook 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

401
Unauthorized Error
404
Not Found Error