Create webhook endpoint | SpeechifyAI API

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.

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_…’.

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

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 (for example workspace.spend_budget.warning) 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. An event’s documentation names the keys it recognises. 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.

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.

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

429

Too Many Requests Error

500

Internal Server Error

Authentication

Headers

Request

Response headers

Response

Errors