Webhooks for pre-recorded audio

Webhooks are custom HTTP callbacks that you can define to get notified when your pre-recorded audio transcripts are ready.

This guide covers webhooks for pre-recorded audio transcription. For webhooks with streaming audio, see Webhooks for streaming speech-to-text.

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

Create a webhook for a transcription

Don’t have a webhook endpoint yet?Create a test webhook endpoint with webhook.site to test your webhook integration.

Python
Python SDK
JavaScript
JavaScript SDK

To create a webhook, set the webhook_url parameter when you create a new transcription. The URL must be accessible from AssemblyAI’s servers.

import requests
import time

base_url = "https://api.assemblyai.com"

headers = {
    "authorization": "<YOUR_API_KEY>"
}

with open("./my-audio.mp3", "rb") as f:
  response = requests.post(base_url + "/v2/upload",
                          headers=headers,
                          data=f)

upload_url = response.json()["upload_url"]

data = {
    "audio_url": upload_url,
    "webhook_url": "https://example.com/webhook"
}

url = base_url + "/v2/transcript"
response = requests.post(url, json=data, headers=headers)

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.

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)

To create a webhook, set the webhook_url parameter when you create a new transcription. The URL must be accessible from AssemblyAI’s servers.

import fs from "fs-extra";

const baseUrl = "https://api.assemblyai.com";

const headers = {
  authorization: "<YOUR_API_KEY>",
};

const path = "./my-audio.mp3";
const audioData = await fs.readFile(path);
let res = await fetch(`${baseUrl}/v2/upload`, {
  method: "POST",
  headers,
  body: audioData,
});
if (!res.ok) throw new Error(`Error: ${res.status}`);
const uploadResponse = await res.json();
const uploadUrl = uploadResponse.upload_url;

const data = {
  audio_url: uploadUrl,
  webhook_url: "https://example.com/webhook",
};

const url = `${baseUrl}/v2/transcript`;
const response = await fetch(url, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(data),
});
if (!response.ok) throw new Error(`Error: ${response.status}`);

To create a webhook, include the webhook_url parameter when you create a new transcription. The URL must be accessible from AssemblyAI’s servers.Use submit() instead of transcribe() to create a transcription without waiting for it to complete.

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({
  apiKey: "<YOUR_API_KEY>",
});

// const audioFile = './local_file.mp3'
const audioFile = "https://assembly.ai/wildfires.mp3";

const params = {
  audio: audioFile,
  webhook_url: "https://example.com/webhook",
};

const run = async () => {
  const transcript = await client.transcripts.submit(params);
};

run();

Handle webhook deliveries

When the transcript is ready, AssemblyAI will send a POST HTTP request to the URL that you specified. Your webhook endpoint must return a 2xx HTTP status code within 10 seconds to indicate successful receipt. If a 2xx status is not received within 10 seconds, AssemblyAI will retry the webhook call up to a total of 10 attempts. If at any point your endpoint returns a 4xx status code, the webhook call is considered failed and will not be retried.

Static Webhook IP addressesAssemblyAI sends all webhook deliveries from fixed IP addresses:

Region	IP Address
US	`44.238.19.20`
EU	`54.220.25.36`

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`.

The webhook payload only contains the transcript_id and status. It doesn’t include the transcript text or error details. If the status is "error", make a GET /v2/transcript/{transcript_id} request to retrieve the error message from the error field in the response. See Retrieve a transcript with the transcript ID below.

Webhook status code

When you retrieve the transcript using the transcript ID, the JSON response will include a webhook_status_code field. This field contains the HTTP status code that AssemblyAI received when calling your webhook endpoint, allowing you to verify that the webhook was delivered successfully.

Retrieve a transcript with the transcript ID

Python
Python SDK
JavaScript
JavaScript SDK

import requests
import time

base_url = "https://api.assemblyai.com"

headers = {
    "authorization": "<YOUR_API_KEY>"
}

transcript_id = "<TRANSCRIPT_ID>"

polling_endpoint = f"https://api.assemblyai.com/v2/transcript/{transcript_id}"

transcription_result = requests.get(polling_endpoint, headers=headers).json()

if transcription_result['status'] == 'completed':
  print(f"Transcript ID: {transcript_id}")
elif transcription_result['status'] == 'error':
  raise RuntimeError(f"Transcription failed: {transcription_result['error']}")

import assemblyai as aai

aai.settings.api_key = "<YOUR_API_KEY>"

transcript = aai.Transcript.get_by_id("<TRANSCRIPT_ID>")

if transcript.status == "error":
  raise RuntimeError(f"Transcription failed: {transcript.error}")

print(transcript.text)

import fs from "fs-extra";

const baseUrl = "https://api.assemblyai.com";

const headers = {
  authorization: "<YOUR_API_KEY>",
};

const transcriptId = "<TRANSCRIPT_ID>";
const pollingEndpoint = `${baseUrl}/v2/transcript/${transcriptId}`;

let res = await fetch(pollingEndpoint, { headers });
if (!res.ok) throw new Error(`Error: ${res.status}`);
const transcriptionResult = await res.json();

if (transcriptionResult.status === "completed") {
  console.log(transcriptionResult.text);
} else if (transcriptionResult.status === "error") {
  throw new Error(`Transcription failed: ${transcriptionResult.error}`);
}

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({
  apiKey: "<YOUR_API_KEY>",
});

const transcript = await client.transcripts.get("<TRANSCRIPT_ID>");

if (transcript.status === "error") {
  throw new Error(`Transcription failed: ${transcript.error}`);
}

console.log(transcript.text);

Authenticate webhook deliveries

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

Python
JavaScript

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

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

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

To add an authentication header, include the webhook_auth_header_name and webhook_auth_header_value parameters.

client.transcripts.submit({
  audio:
    'https://assembly.ai/wildfires.mp3',
  webhook_url: 'https://example.com/webhook',
  webhook_auth_header_name: "X-My-Webhook-Secret",
  webhook_auth_header_value: "secret-value"
})

Python
Python SDK
JavaScript
JavaScript SDK

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

import requests
import time

base_url = "https://api.assemblyai.com"

headers = {
    "authorization": "<YOUR_API_KEY>"
}

with open("./my-audio.mp3", "rb") as f:
  response = requests.post(base_url + "/v2/upload",
                          headers=headers,
                          data=f)

upload_url = response.json()["upload_url"]

data = {
    "audio_url": upload_url,
    "webhook_url": "https://example.com/webhook",
    "webhook_auth_header_name": "X-My-Webhook-Secret",
    "webhook_auth_header_value": "secret-value"
}

url = base_url + "/v2/transcript"
response = requests.post(url, json=data, headers=headers)

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

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", "X-My-Webhook-Secret", "secret-value")

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

To add an authentication header, include the webhook_auth_header_name and webhook_auth_header_value parameters.

import fs from "fs-extra";

const baseUrl = "https://api.assemblyai.com";

const headers = {
  authorization: "<YOUR_API_KEY>",
};

const path = "./my-audio.mp3";
const audioData = await fs.readFile(path);
let res = await fetch(`${baseUrl}/v2/upload`, {
  method: "POST",
  headers,
  body: audioData,
});
if (!res.ok) throw new Error(`Error: ${res.status}`);
const uploadResponse = await res.json();
const uploadUrl = uploadResponse.upload_url;

const data = {
  audio_url: uploadUrl,
  webhook_url: "https://example.com/webhook",
  webhook_auth_header_name: "X-My-Webhook-Secret",
  webhook_auth_header_value: "secret-value",
};

const url = `${baseUrl}/v2/transcript`;
const response = await fetch(url, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(data),
});
if (!response.ok) throw new Error(`Error: ${response.status}`);

To add an authentication header, include the webhook_auth_header_name and webhook_auth_header_value parameters.

import { AssemblyAI } from "assemblyai";

const client = new AssemblyAI({
  apiKey: "<YOUR_API_KEY>",
});

// const audioFile = './local_file.mp3'
const audioFile = "https://assembly.ai/wildfires.mp3";

const params = {
  audio: audioFile,
  webhook_url: "https://example.com/webhook",
  webhook_auth_header_name: "X-My-Webhook-Secret",
  webhook_auth_header_value: "secret-value",
};

const run = async () => {
  const transcript = await client.transcripts.submit(params);
};

run();

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.

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.

Documentation Index

​Create a webhook for a transcription

​Handle webhook deliveries

​Delivery payload

​Webhook status code

​Retrieve a transcript with the transcript ID

​Authenticate webhook deliveries

​Add metadata to webhook deliveries

​Failed webhook deliveries

Create a webhook for a transcription

Handle webhook deliveries

Delivery payload

Webhook status code

Retrieve a transcript with the transcript ID

Authenticate webhook deliveries

Add metadata to webhook deliveries

Failed webhook deliveries