Create a webhook subscription

Register one destination for transcription.completed, transcription.failed, or both. The response reveals a signing secret once so the receiver can verify every delivery.

POST/api/v1/webhook-subscriptions201 Created

Use this endpoint OpenAPI spec

Authentication

Send an active Fast Transcriber API key as an HTTP bearer token.

Authorization: Bearer ft_live_replace_me

Request

Use the fields below and send a JSON body.

Field	Type	Description
`url`required	uri	Public HTTPS receiver on port 443, up to 2,048 characters. Private, local, credential-bearing, and fragment URLs are rejected.
`events`required	string[]	One or both supported event types: transcription.completed and transcription.failed.

curl --include --request POST https://fast-transcriber.com/api/v1/webhook-subscriptions \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "events": ["transcription.completed", "transcription.failed"]
  }'

Response

Successful JSON responses use a top-level data envelope. A 204 response has no body.

Field	Type	Description
`Location header`	string	Relative URL for the created subscription.
`data.id`	uuid	Stable subscription identifier.
`data.url`	uri	Validated delivery destination. Only the create response returns the full URL.
`data.events`	string[]	Subscribed event types.
`data.status`	active \| disabled	Current delivery status.
`data.created_at`	date-time	UTC subscription creation timestamp.
`data.disabled_at`	date-time \| null	UTC disable timestamp, or null while active.
`data.signing_secret`	string	Create-only whsec_ secret used to verify signed deliveries. It is never returned again.

{
  "data": {
    "created_at": "2026-09-04T10:12:00.000Z",
    "disabled_at": null,
    "events": ["transcription.completed", "transcription.failed"],
    "id": "b7140faa-1234-4abc-9def-0123456789ab",
    "signing_secret": "whsec_save_this_value_now",
    "status": "active",
    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
  }
}

Errors

API errors return a machine-readable code and message.

Status	Code	Meaning
401	`missing_api_key`	No bearer key was supplied.
401	`invalid_api_key`	The bearer key is malformed, unknown, or revoked.
400	`invalid_request`	The request body is not a JSON object.
400	`invalid_webhook_url`	url is missing, invalid, non-HTTPS, non-public, or otherwise unsafe.
400	`invalid_webhook_events`	events is empty or contains an unsupported event type.
409	`webhook_subscription_limit_reached`	The account already has 20 active webhook subscriptions.
503	`webhooks_unavailable`	Webhook subscription secrets cannot be stored safely with the current service configuration.

Implementation notes

Store signing_secret in a secret manager when you create the subscription. List responses never reveal it.
A subscription receives matching terminal transcription events for the authenticated account, regardless of whether the job was created through REST, MCP, or the web product.
An account can keep up to 20 active webhook subscriptions.
Delete and recreate a subscription to rotate its signing secret or change its destination and event selection.