Asynchronous Speech to Text

Overview

Webhooks allow you to receive automatic notifications when your Speech to Text transcription tasks are completed, eliminating the need to continuously poll the API for status updates. This is particularly useful for long-running transcription jobs or when processing large volumes of audio files.

When a transcription is completed, ElevenLabs will send a POST request to your specified webhook URL with the transcription results, including the transcript text, language detection, and any metadata.

Using webhooks

1

Create or edit a webhook

In the ElevenLabs dashboard, go to Developers > Webhooks. Click Create webhook, or edit an existing webhook.

Configure the webhook with:

• Name: A descriptive name for your webhook
• Callback URL: Your publicly accessible HTTPS endpoint
• Webhook Auth Method: Either HMAC or OAuth. It is up to the client to implement the verification mechanism. ElevenLabs sends headers that allow for verification but we do not enforce it.
• Events: Select Transcription completed.

2

Make API calls with webhook parameter enabled

When making speech-to-text API calls, include the webhook parameter set to true to enable webhook notifications for that specific request.

PythonTypeScript

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(
  api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def transcribe_with_webhook(audio_file):
  try:
    result = elevenlabs.speech_to_text.convert(
      file=audio_file,
      model_id="scribe_v2",
      webhook=True,
    )
    print(f"Transcription started: {result.request_id}")
    return result
  except Exception as e:
    print(f"Error starting transcription: {e}")
    raise e

Webhook payload

When a transcription is completed, your webhook endpoint will receive a POST request with the transcription and webhook data:

{
  type: 'speech_to_text_transcription',
  data: {
    request_id: 'some-request-id-123',
    webhook_metadata: { ... }, // if provided in the convert request
    transcription: {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        },
        {
          "text": " ",
          "start": 0.5,
          "end": 0.5,
          "type": "spacing",
          "speaker_id": "speaker_1"
        },
        {
          "text": "world!",
          "start": 0.5,
          "end": 1.2,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}

Please refer to the Speech-to-text API reference to learn about the details of the response structure.

If the request included a transcript_edit instruction, the transcription object also contains an edited_transcript field with the edited text.

If the transcription fails, your endpoint receives a webhook_error event instead. It has no data object: it carries a top-level request_id (the same id returned when the request was accepted), an error_message and the request’s webhook_metadata.

Implementing your webhook endpoint

Here’s an example of how to implement a webhook endpoint to handle incoming notifications:

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import express from "express";
const elevenlabs = new ElevenLabsClient();
const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
// The raw body is required: verification runs over the exact bytes sent.
app.post("/webhook/speech-to-text", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["elevenlabs-signature"];
  let event;
  try {
    event = await elevenlabs.webhooks.constructEvent(
      req.body.toString(),
      signature,
      WEBHOOK_SECRET
    );
  } catch (error) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  if (event.type === "speech_to_text_transcription") {
    const { request_id, transcription } = event.data;
    console.log(`Transcription ${request_id} completed`);
    console.log(`Language: ${transcription.language_code}`);
    console.log(`Text: ${transcription.text}`);
    processTranscription(request_id, transcription);
  } else if (event.type === "webhook_error") {
    console.error(`Transcription ${event.request_id} failed: ${event.error_message}`);
    handleTranscriptionError(event.request_id, event.webhook_metadata, event.error_message);
  }
  res.status(200).json({ received: true });
});
async function processTranscription(requestId, transcription) {
  console.log("Processing completed transcription...");
}
async function handleTranscriptionError(requestId, webhookMetadata, errorMessage) {
  console.log("Handling transcription error...");
}
app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});

Security considerations

Signature verification

Always verify webhook signatures to ensure requests came from ElevenLabs.

HTTPS requirement

Webhook URLs must use HTTPS to ensure secure transmission of transcription data.

Rate limiting

Implement rate limiting on your webhook endpoint to prevent abuse:

import rateLimit from "express-rate-limit";
const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // limit each IP to 100 requests per windowMs
  message: "Too many webhook requests from this IP",
});
app.use("/webhook", webhookLimiter);

Failure responses

Return a 2xx status code to acknowledge the webhook.

By default, Speech to Text transcription webhooks are delivered once. Every non-2xx response counts as a failed delivery, and repeated failures auto-disable the webhook.

If you turn on retries for the webhook, failed deliveries (5xx, 408, 429 or connection errors) are retried up to 5 more times, roughly 30 seconds, 2 minutes, 8 minutes, 30 minutes and 30 minutes after the previous attempt. Other 4xx responses are not retried. Every attempt for the same event carries the same ElevenLabs-Webhook-Delivery-Id header, so your handler can ignore duplicates.

Requests made with enable_logging set to false (zero retention mode) get up to 2 quick retries, 5 seconds and 30 seconds after the previous attempt, when retries are turned on. The transcript is never stored.

If a delivery still fails, fetch the result with Get transcript using the transcription_id returned when the request was accepted. Transcripts are not stored for requests made with enable_logging set to false.

Testing webhooks

Local development

For local testing, use tools like ngrok to expose your local server:

ngrok http 3000

Use the provided HTTPS URL as your webhook endpoint during development.

Webhook testing

You can test your webhook implementation by making a transcription request and monitoring your endpoint:

async function testWebhook() {
  const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });
  const result = await elevenlabs.speechToText.convert({
    file: audioFile,
    modelId: "scribe_v2",
    webhook: true,
  });
  console.log("Test transcription started:", result.requestId);
}

Next steps