Webhooks

Instead of polling, register a webhook to be pushed an event when a transcription finishes. This is the recommended approach at scale and for tools like n8n.

Register an endpoint

Add a webhook in Settings → API → Webhooks. Choose the events to subscribe to:

• transcription_completed
• transcription_failed

The signing secret (prefixed whsec_) is shown once — store it to verify deliveries.

Payload

We POST JSON to your endpoint:

{
  "id": "delivery-uuid",
  "event": "transcription_completed",
  "data": { "transcriptionId": "…" },
  "createdAt": "2026-06-18T12:00:00.000Z"
}

Use the transcriptionId to fetch the full result. The id is the delivery id — dedupe on it, since a delivery may be retried.

Verifying signatures

Each delivery includes an X-Signature header:

X-Signature: sha256=<hex hmac>

It's the HMAC-SHA256 of the raw request body using your webhook secret. Recompute it and compare in constant time:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Retries

Failed deliveries retry with exponential backoff (up to 6 attempts). Return any 2xx status to mark a delivery as acknowledged.

Using with n8n

Add an HTTP Request node to create the transcription, and a Webhook trigger node whose URL you register here. The completion event resumes your workflow — no polling.