Using webhooks

    Instead of polling for the result of your transcription, you can submit a webhook URL that we'll make a POST request to once your transcript is complete or if there was an error transcribing your audio file.

    Specify your webhook URL

    When submitting an audio file for transcription, you can include the additional parameter "webhook_url". This must be a URL on your server that can be reached by our backend.

    Receiving the webhook

    You'll receive a webhook when your transcription goes to status completed, or when your transcription goes to status error. In either case, a POST request will be made to your webhook url. The headers and body will look like this:

    content-length: 79
    accept-encoding: gzip, deflate
    accept: */*
    user-agent: python-requests/2.21.0
    content-type: application/json
    request body
    status: completed
    transcript_id: 5552493-16d8-42d8-8feb-c2a16b56f6e8

    Once you receive the webhook, you can make a GET request to /v2/transcript to fetch the final result of your transcription.

    After you make your GET request, you'll get a response back like this:

        "acoustic_model": "assemblyai_default",
        "audio_duration": 12.0960090702948,
        "audio_url": "",
        "confidence": 0.956,
        "dual_channel": null,
        "format_text": true,
        "id": "5552493-16d8-42d8-8feb-c2a16b56f6e8",
        "language_model": "assemblyai_default",
        "punctuate": true,
        "status": "completed",
        "text": "You know Demons on TV like that and and for people to expose themselves to being rejected on TV or humiliated by fear factor or.",
        "utterances": null,
        "webhook_status_code": 200,
        "webhook_url": "",
        "words": [
                "confidence": 1.0,
                "end": 440,
                "start": 0,
                "text": "You"
                "confidence": 0.96,
                "end": 10060,
                "start": 9600,
                "text": "factor"
                "confidence": 0.97,
                "end": 10260,
                "start": 10080,
                "text": "or."

    In the response, you'll see the "webhook_status_code" is 200, reflecting that the webhook was made successfully.

    Including custom parameters in your webhook request

    Often times, you'll want to associate certain meta data with your transcription request, such as a customer ID. The easiest way to do this is to include this parameter in your webhook URL, for example:

    Then, when you receive the webhook, you can parse these parameters out of the webhook URL.

    Failed webhooks and retries

    If we get a non 200 response when we POST to your webhook url, we'll retry the request 10 times, with a 10 second interval between each retry. After all 10 retries fail, we'll consider the webhook to be permanently failed, and will set the "webhook_status_code" in the JSON response to the status code we received from your webhook URL (eg, 404, 500, 400, etc.). If we are unable to reach your webhook URL (usually caused by a timeout), we'll use a special status code of 999.