API ReferenceWebhooks

Rotate webhook endpoint secret

Beta

Mint a new HMAC signing secret for the endpoint and return it in the response secret field (shown exactly once). The previous secret stops signing immediately, so accept both during your cutover window.

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 endpoint, including its new one-time 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
403
Forbidden Error
404
Not Found Error