Asynchronous Speech to Text

This guide shows you how to use webhooks to receive asynchronous notifications when transcription tasks complete.

How-to guide · Assumes you have completed the Speech to Text quickstart.

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

This guide assumes you have set up your API key and SDK. Complete the quickstart first if you haven’t.

Create a webhook endpoint

First, create a webhook in the ElevenLabs dashboard. Navigate to your webhooks settings and click “Create Webhook”.

Create webhook interface — Create a new webhook in the ElevenLabs dashboard

Configure your 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.

Associate webhook with transcription tasks

Once created, you can associate the webhook with your speech-to-text tasks. In the dashboard, navigate to the webhook events section and link your webhooks to speech-to-text events.

Webhook association interface — Associate webhook with speech-to-text tasks

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.

1 from dotenv import load_dotenv
2 from elevenlabs.client import ElevenLabs
3 
4 load_dotenv()
5 
6 elevenlabs = ElevenLabs(
7   api_key=os.getenv("ELEVENLABS_API_KEY"),
8 )
9 
10 def transcribe_with_webhook(audio_file):
11   try:
12     result = elevenlabs.speech_to_text.convert(
13       file=audio_file,
14       model_id="scribe_v2",
15       webhook=True,
16     )
17     print(f"Transcription started: {result.request_id}")
18     return result
19   except Exception as e:
20     print(f"Error starting transcription: {e}")
21     raise e

Webhook payload

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

1 {
2   type: 'speech_to_text_transcription',
3   data: {
4     request_id: 'some-request-id-123',
5     webhook_metadata: { ... }, // if provided in the convert request
6     transcription: {
7       "language_code": "en",
8       "language_probability": 0.98,
9       "text": "Hello world!",
10       "words": [
11         {
12           "text": "Hello",
13           "start": 0.0,
14           "end": 0.5,
15           "type": "word",
16           "speaker_id": "speaker_1"
17         },
18         {
19           "text": " ",
20           "start": 0.5,
21           "end": 0.5,
22           "type": "spacing",
23           "speaker_id": "speaker_1"
24         },
25         {
26           "text": "world!",
27           "start": 0.5,
28           "end": 1.2,
29           "type": "word",
30           "speaker_id": "speaker_1"
31         }
32       ]
33     }
34   }
35 }

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

Implementing your webhook endpoint

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

1 import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
2 import 'dotenv/config';
3 import express from 'express';
4 
5 const elevenlabs = new ElevenLabsClient();
6 
7 const app = express();
8 app.use(express.json());
9 
10 const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
11 
12 app.post('/webhook/speech-to-text', (req, res) => {
13   try {
14     const signature = req.headers['elevenlabs-signature'];
15     const payload = JSON.stringify(req.body);
16     let event;
17 
18     try {
19       // Verify the webhook signature.
20       event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
21     } catch (error) {
22       return res.status(401).json({ error: 'Invalid signature' });
23     }
24 
25     if (event.type === 'speech_to_text.completed') {
26       const { requestId, status, text, language_code } = event.data;
27 
28       console.log(`Transcription ${requestId} completed`);
29       console.log(`Language: ${language_code}`);
30       console.log(`Text: ${text}`);
31 
32       processTranscription(requestId, text, language_code);
33     } else if (status === 'failed') {
34       console.error(`Transcription ${requestId} failed`);
35       handleTranscriptionError(requestId);
36     }
37 
38     res.status(200).json({ received: true });
39   } catch (error) {
40     console.error('Webhook error:', error);
41     res.status(500).json({ error: 'Internal server error' });
42   }
43 });
44 
45 async function processTranscription(requestId, text, language) {
46   console.log('Processing completed transcription...');
47 }
48 
49 async function handleTranscriptionError(requestId) {
50   console.log('Handling transcription error...');
51 }
52 
53 app.listen(3000, () => {
54   console.log('Webhook server listening on port 3000');
55 });

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:

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

Failure responses

Return appropriate HTTP status codes:

200-299: Success - webhook processed successfully
400-499: Client error - webhook will not be retried
500-599: Server error - webhook will be retried

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:

1 async function testWebhook() {
2   const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });
3 
4   const result = await elevenlabs.speechToText.convert({
5     file: audioFile,
6     modelId: "scribe_v2",
7     webhook: true,
8   });
9 
10   console.log("Test transcription started:", result.requestId);
11 }

Next steps

Server-side streaming

Transcribe audio in real time using the WebSocket-based streaming API.

API reference

Full Speech to Text API reference and parameters.

1	from dotenv import load_dotenv
2	from elevenlabs.client import ElevenLabs
3
4	load_dotenv()
5
6	elevenlabs = ElevenLabs(
7	api_key=os.getenv("ELEVENLABS_API_KEY"),
8	)
9
10	def transcribe_with_webhook(audio_file):
11	try:
12	result = elevenlabs.speech_to_text.convert(
13	file=audio_file,
14	model_id="scribe_v2",
15	webhook=True,
16	)
17	print(f"Transcription started: {result.request_id}")
18	return result
19	except Exception as e:
20	print(f"Error starting transcription: {e}")
21	raise e

1	{
2	type: 'speech_to_text_transcription',
3	data: {
4	request_id: 'some-request-id-123',
5	webhook_metadata: { ... }, // if provided in the convert request
6	transcription: {
7	"language_code": "en",
8	"language_probability": 0.98,
9	"text": "Hello world!",
10	"words": [
11	{
12	"text": "Hello",
13	"start": 0.0,
14	"end": 0.5,
15	"type": "word",
16	"speaker_id": "speaker_1"
17	},
18	{
19	"text": " ",
20	"start": 0.5,
21	"end": 0.5,
22	"type": "spacing",
23	"speaker_id": "speaker_1"
24	},
25	{
26	"text": "world!",
27	"start": 0.5,
28	"end": 1.2,
29	"type": "word",
30	"speaker_id": "speaker_1"
31	}
32	]
33	}
34	}
35	}

1	import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
2	import 'dotenv/config';
3	import express from 'express';
4
5	const elevenlabs = new ElevenLabsClient();
6
7	const app = express();
8	app.use(express.json());
9
10	const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
11
12	app.post('/webhook/speech-to-text', (req, res) => {
13	try {
14	const signature = req.headers['elevenlabs-signature'];
15	const payload = JSON.stringify(req.body);
16	let event;
17
18	try {
19	// Verify the webhook signature.
20	event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
21	} catch (error) {
22	return res.status(401).json({ error: 'Invalid signature' });
23	}
24
25	if (event.type === 'speech_to_text.completed') {
26	const { requestId, status, text, language_code } = event.data;
27
28	console.log(`Transcription ${requestId} completed`);
29	console.log(`Language: ${language_code}`);
30	console.log(`Text: ${text}`);
31
32	processTranscription(requestId, text, language_code);
33	} else if (status === 'failed') {
34	console.error(`Transcription ${requestId} failed`);
35	handleTranscriptionError(requestId);
36	}
37
38	res.status(200).json({ received: true });
39	} catch (error) {
40	console.error('Webhook error:', error);
41	res.status(500).json({ error: 'Internal server error' });
42	}
43	});
44
45	async function processTranscription(requestId, text, language) {
46	console.log('Processing completed transcription...');
47	}
48
49	async function handleTranscriptionError(requestId) {
50	console.log('Handling transcription error...');
51	}
52
53	app.listen(3000, () => {
54	console.log('Webhook server listening on port 3000');
55	});

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

1	async function testWebhook() {
2	const audioFile = new File([audioBuffer], "test.mp3", { type: "audio/mp3" });
3
4	const result = await elevenlabs.speechToText.convert({
5	file: audioFile,
6	modelId: "scribe_v2",
7	webhook: true,
8	});
9
10	console.log("Test transcription started:", result.requestId);
11	}