API ReferenceWebhooks

Create webhook endpoint

Beta
Register a webhook endpoint. Speechify mints an HMAC signing secret and returns it in the response `secret` field — exactly once. Store it then; subsequent reads omit it (rotate it with the rotate-secret action if lost). Select events via `enabled_events`: a list of catalog event names or `["*"]` for every event. Optionally scope delivery to one project with `project_id`; omit it for a workspace-wide endpoint that receives every project's events. Limited to 50 endpoints per workspace.

Authentication

AuthorizationBearer

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

Headers

Speechify-VersionstringOptional

Request

This endpoint expects an object.
urlstringRequiredformat: "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.

enabled_eventslist of stringsRequired

Catalog event names to subscribe to, or ["*"] for all events.

project_idstring or nullOptional

Optionally scope the endpoint to one project (prefixed proj_... id): a scoped endpoint receives only that project’s events. Omit (or null) for workspace-wide - it receives every project’s events. An unknown id returns 404 project_not_found. A project-pinned API key creates into its own project and cannot name the workspace-wide tier.

includelist of stringsOptional

Optional payload-shaping keys (see WebhookEndpoint.include): messages, evaluations. Omit for the lean default.

api_versiondateOptional

Optionally pin the endpoint’s payload shape to a dated version (YYYY-MM-DD, see WebhookEndpoint.api_version). Omit to use the workspace’s current version. An unknown version is rejected.

descriptionstring or nullOptional

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 created endpoint, including its 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

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error