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
Create a webhook endpoint
First, create a webhook in the ElevenLabs dashboard. Navigate to your webhooks settings and click “Create Webhook”.

Configure your webhook with:
- Name: A descriptive name for your webhook
- Callback URL: Your publicly accessible HTTPS endpoint
- Webhook Auth Method: Either
HMAC
orOAuth
. 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.

Create an API key
Create an API key in the dashboard here, which you’ll use to securely access the API.
Store the key as a managed secret and pass it to the SDKs either as a environment variable via an .env
file, or directly in your app’s configuration depending on your preference.
Webhook payload
When a transcription is completed, your webhook endpoint will receive a POST request with the identical payload as the non-webhook API:
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:
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:
Failure responses
Return appropriate HTTP status codes:
200-299
: Success - webhook processed successfully400-499
: Client error - webhook will not be retried500-599
: Server error - webhook will be retried
Testing webhooks
Local development
For local testing, use tools like ngrok to expose your local server:
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: