Outgoing webhooks

Receive signed, retryable events when a transcription completes or fails.

Field	Type	Description
`transcription.completed`	event	The transcript result is ready to retrieve.
`transcription.failed`	event	Processing stopped; retrieve the job to inspect its error.

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"]
  }'

Save the signing secret now

The signing_secret is returned only by this create response. Store it in a secret manager; list responses never reveal it.

The destination must be a public HTTPS URL on port 443. URLs that resolve to private or local addresses, contain credentials or a fragment, or require following a redirect are not accepted for delivery.

Use the thin event payload

Notifications identify the terminal job without embedding transcript text or segments.

{
  "id": "5f538c74-1234-4abc-9def-0123456789ab",
  "type": "transcription.completed",
  "created_at": "2026-09-04T10:42:16.000Z",
  "data": {
    "id": "95c3fdd8-1234-4abc-9def-0123456789ab",
    "filename": "interview.mp3",
    "status": "completed",
    "duration_seconds": 1842,
    "resource_url": "https://fast-transcriber.com/api/v1/transcriptions/95c3fdd8-1234-4abc-9def-0123456789ab"
  }
}

Field	Type	Description
`id`required	uuid	Stable event identifier; it matches the webhook-id header and stays unchanged across retries.
`type`required	string	transcription.completed or transcription.failed.
`created_at`required	date-time	UTC time when the terminal event was created.
`data.id`required	uuid	Transcription job identifier.
`data.filename`required	string	Original upload name or derived source label.
`data.status`required	completed \| failed	Terminal job state corresponding to the event type.
`data.duration_seconds`required	integer \| null	Detected media duration when available.
`data.resource_url`required	uri	Authenticated job resource used to fetch transcript text, segments, or a failure error.

curl "$RESOURCE_URL" \
  --header "Authorization: Bearer $FAST_TRANSCRIBER_API_TOKEN"

Keep bearer authentication server-side

Verify the event first, then GET data.resource_url with an API key owned by the same account. Do not send the API key to the webhook destination in a query string.

Verify every signature

Fast Transcriber uses the Standard Webhooks header format and an HMAC-SHA256 signature.

webhook-id: 5f538c74-1234-4abc-9def-0123456789ab
webhook-timestamp: 1788518536
webhook-signature: v1,BASE64_HMAC_SHA256

key = base64_decode(signing_secret without the "whsec_" prefix)
signed_content = webhook-id + "." + webhook-timestamp + "." + raw_request_body
expected = base64(HMAC-SHA256(key, signed_content))

Read the exact raw request bytes before parsing or re-serializing JSON.
Use a Standard Webhooks library where one is available, and compare signatures in constant time.
Reject timestamps outside your replay window and never expose the whsec_ secret to browser code, logs, or workflow output.

Design for at-least-once delivery

A valid 2xx response acknowledges an event; transient failures are retried with backoff.

Acknowledge durably

Persist or enqueue the verified event, then return 2xx promptly. Timeouts and retryable responses can produce another attempt.

Deduplicate

Keep webhook-id in a unique store. It remains stable across retries even though the timestamp and signature are refreshed.

Reconcile

A duplicate can arrive after your receiver accepted an event but its acknowledgement was not recorded. Periodic list or GET checks can repair missed work.

Fail closed

Do not process an event with an invalid signature, stale timestamp, unsupported type, or mismatched type and status.

At least once is not exactly once

Make downstream actions idempotent. Sending an email, creating a Zapier item, or writing a row should be guarded by the event ID.

Fast Transcriber retries network failures and non-2xx responses up to seven total attempts. A 410 Gone response instead disables the subscription immediately and cancels its queued deliveries.

Manage and rotate subscriptions

01
Create
Register the destination and event types, then save the create-only signing secret.
02
Inspect
GET the collection to view subscription IDs, event selections, status, and redacted destination origins.
03
Replace
Delete and recreate the subscription to rotate its secret or change its URL or events.

During rotation, let the receiver recognize event IDs from both subscriptions until the new path is verified, then delete the old subscription. Deletion returns 204 and stops future attempts. If a receiver returned 410, fix it and delete/recreate the now-disabled subscription.

Outgoing webhooks

Acknowledge durably

Deduplicate

Reconcile

Fail closed

Create

Inspect

Replace

List subscriptions

Delete a subscription