Webhooks

Webhooks are custom HTTP callbacks that you can define to get notified when your transcripts are ready

To use webhooks, you need to set up your own webhook receiver to handle webhook deliveries.

Create a webhook for a transcription

To create a webhook, use set_webhook() on the transcription config. The URL must be accessible from AssemblyAI’s servers.

Use submit() instead of transcribe() to create a transcription without waiting for it to complete.

Python

import assemblyai as aai

aai.settings.api_key = "YOUR_API_KEY"

# audio_file = "./local_file.mp3"
audio_file = "https://assembly.ai/wildfires.mp3"

config = aai.TranscriptionConfig().set_webhook("https://example.com/webhook")

aai.Transcriber().submit(audio_file, config)

Handle webhook deliveries

When the transcript is ready, AssemblyAI will send a POST HTTP request to the URL that you specified.

Sender’s IP address

AssemblyAI sends all webhook deliveries from the same IP address, 44.238.19.20.

Delivery payload

The webhook delivery payload contains a JSON object with the following properties:

{transcript_id:"5552493-16d8-42d8-8feb-c2a16b56f6e8",status:"completed"}

Key	Type	Description
transcript_id	string	The ID of the transcript.
status	string	The status of the transcript. Either completed or error.

Authenticate webhook deliveries

You can authenticate webhook deliveries from AssemblyAI by including a custom HTTP header in the request.

To add an authentication header, include the auth header name and value in set_webhook().

Python

config = aai.TranscriptionConfig().set_webhook(
    "https://example.com/webhook", "X-My-Webhook-Secret", "secret-value"
)

aai.Transcriber().submit(audio_url, config)

Add metadata to webhook deliveries

To associate metadata for a specific transcription request, you can add your own query parameters to the webhook URL.

https://example.com/webhook?customer_id=1234&order_id=5678

Now, when you receive the webhook delivery, you’ll know the customer who requested it.

Handling failed webhook deliveries

Webhook deliveries can fail for multiple reasons. For example, if your server is down or takes more than 10 seconds to respond.

If a webhook delivery fails, AssemblyAI will attempt to redeliver it up to 10 times, waiting 10 seconds between each attempt. If all attempts fail, AssemblyAI considers the delivery as permanently failed.

submit() returns an object with the ID of the transcription. If the webhook delivery fails, you can use this ID to retrieve the transcript later.