Webhooks - AssemblyAI Docs

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.

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)

import { AssemblyAI } from 'assemblyai'

const client = new AssemblyAI({
  apiKey: 'YOUR_API_KEY'
})

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

client.transcripts.submit({
  audio: audioFile,
  webhook_url: 'https://example.com/webhook'
})

package main

import (
    "context"

    aai "github.com/AssemblyAI/assemblyai-go-sdk"
)

func main() {
    ctx := context.Background()

    client := aai.NewClient("YOUR_API_KEY")

    // For local files see our Getting Started guides.
    audioURL := "https://assembly.ai/wildfires.mp3"

    _, _ = client.Transcripts.SubmitFromURL(ctx, audioURL, &aai.TranscriptOptionalParams{
        WebhookURL:             aai.String("https://example.com/webhook"),
    })
}

import com.assemblyai.api.AssemblyAI;
import com.assemblyai.api.resources.transcripts.types.*;

public final class App {
    public static void main(String... args) {
        AssemblyAI client = AssemblyAI.builder()
                .apiKey("YOUR_API_KEY")
                .build();

        // For local files see our Getting Started guides.
        String audioUrl = "https://assembly.ai/wildfires.mp3";

        var params = TranscriptOptionalParams.builder()
                .webhookUrl("https://example.com/webhook")
                .build();

        Transcript transcript = client.transcripts().submit(audioUrl, params);
    }
}

using AssemblyAI;
using AssemblyAI.Transcripts;

var client = new AssemblyAIClient("YOUR_API_KEY");

// For local files see our Getting Started guides.
const string audioUrl = "https://assembly.ai/wildfires.mp3";

var transcriptParams = new TranscriptParams
{
    AudioUrl = audioUrl,
    WebhookUrl = "https://example.com/webhook"
};

var transcript = await client.Transcripts.SubmitAsync(transcriptParams);

require 'assemblyai'

client = AssemblyAI::Client.new(api_key: 'YOUR_API_KEY')

# For local files see our Getting Started guides.
audio_url = 'https://assembly.ai/sports_injuries.mp3'

transcript = client.transcripts.submit(
  audio_url: audio_url,
  webhook_url: 'https://example.com/webhook'
)

Handle webhook deliveries

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

Sender’s IP addressAssemblyAI 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().

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

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

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"
})

client.Transcripts.SubmitFromURL(ctx, audioURL, &aai.TranscriptOptionalParams{
    WebhookURL:             aai.String("https://example.com/webhook"),
    WebhookAuthHeaderName:  aai.String("X-My-Webhook-Secret"),
    WebhookAuthHeaderValue: aai.String("secret-value"),
})

var params = TranscriptOptionalParams.builder()
        .webhookUrl("https://example.com/webhook")
        .webhookAuthHeaderName("X-My-Webhook-Secret")
        .webhookAuthHeaderValue("secret-value")
        .build();

var transcriptParams = new TranscriptParams
{
    AudioUrl = audioUrl,
    WebhookUrl = "https://example.com/webhook",
    WebhookAuthHeaderName = "X-My-Webhook-Secret",
    WebhookAuthHeaderValue = "secret-value"
};

transcript = client.transcripts.submit(
  audio_url: audio_url,
  webhook_url: 'https://example.com/webhook',
  webhook_auth_header_value: 'X-My-Webhook-Secret',
  webhook_auth_header_name: 'secret-value'
)

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.

​Create a webhook for a transcription

​Handle webhook deliveries

​Delivery payload

​Authenticate webhook deliveries

​Add metadata to webhook deliveries

​Handling failed webhook deliveries

Create a webhook for a transcription

Handle webhook deliveries

Delivery payload

Authenticate webhook deliveries

Add metadata to webhook deliveries

Handling failed webhook deliveries