Skip to main content

Using webhooks

Webhooks allow you to receive real-time updates about the status of your transcription request, without having to poll the API repeatedly.

Setting it up​

You can set them up when submitting a transcription request by including the webhook_url parameter in your request. The parameter must be a URL that can be reached by AssemblyAI's API.

You'll receive a POST request once your transcription is complete or if there was an error transcribing your audio file.

Receiving the request​

  1. 1

    AssemblyAI sends a POST request from a static IP address: 44.238.19.20. When you receive a webhook request from AssemblyAI, the request includes the following headers.

    content-type: application/json
    content-length: 82
    accept: */*
    accept-encoding: gzip, deflate
    user-agent: python-requests/2.25.1
  2. 2

    And the request body includes the following parameters.

    transcript_id: 5552493-16d8-42d8-8feb-c2a16b56f6e8
    status: completed

    The transcript_id field contains the ID of the completed transcription, and the status field indicates whether the transcription was completed successfully or if there was an error.

    If the status returned is error, you can make a GET request using the transcript_id to get more information on the error.

Custom authentication​

You can include a custom header for added security to authenticate webhook requests from AssemblyAI.

This allows you to provide a value to be used as a header on the returning webhook from AssemblyAI, giving the ability to validate incoming requests. Set it up by including two additional parameters in your request: webhook_auth_header_name and webhook_auth_header_value.

Custom parameters​

Oftentimes, you'll want to associate certain metadata with your transcription request, such as a customer ID, and have that passed back to your webhook. The easiest way to do this is to include these parameters in your webhook URL as query parameters.

Handling errors and retries​

If AssemblyAI receives a non-2xx response while attempting to send a webhook request to your specified URL, the request will be retried up to 10 times, with a 10-second interval between each attempt. If all 10 attempts fail, the webhook will be considered permanently failed.

However, if AssemblyAI is unable to reach your webhook URL (typically due to a timeout or if your server is offline), no additional retries will be made.

© AssemblyAI