Create webhook endpoint
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
Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.
Headers
Request
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.
Catalog event names to subscribe to, or ["*"] for all events.
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.
Optional payload-shaping keys (see WebhookEndpoint.include).
Omit for the lean default.
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.
Response headers
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_idfield 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.
Prefixed wire id (whe_<26 char Crockford base32>).
The events this endpoint receives: a list of catalog event names
(for example workspace.spend_budget.warning) or ["*"] for
every event, current and future.
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. An event’s documentation names the
keys it recognises. Empty = lean.
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.
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.
An event is routed by the project frozen on the row that
produced it (an API key’s project, for example), and for a
project.spend_budget.* event the project itself.
Workspace-level events such as workspace.spend_budget.* belong
to no project and reach workspace-wide endpoints only, so a
scoped endpoint subscribed to those alone is refused with a 400
naming enabled_events rather than accepted and never delivered
to. A scoped endpoint records no delivery for another project’s
events.
Optional human-readable label for the endpoint.
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.