Getting webhooks when transcriptions are done

    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.

    Making the Request

    When submitting your request to /v2/transcript, you can include the additional parameter webhook_url. This must be a URL on your server that is reachable by our backend.

    curl --request POST \
      --url https://api.assemblyai.com/v2/transcript \
      --header 'authorization: YOUR-API-TOKEN' \
      --header 'content-type: application/json' \
      --data '
        {
            "audio_url": "https://s3-us-west-2.amazonaws.com/blog.assemblyai.com/audio/8-7-2018-post/7510.mp3",
            "webhook_url": "https://postb.in/1561597007927-8767862515524"
        }'

    Receiving the Webhook

    You'll receive a webhook in 2 scenarios. Either when your transcription goes to status completed or when your transcription goes to status error. In either case, this is what the POST request to your webhook url will look like:

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

    Once you receive the webhook, you can make a GET request to /v2/transcript to query for all of the details of your transcription.

    curl --request GET \
      --url https://api.assemblyai.com/v2/transcript/5552493-16d8-42d8-8feb-c2a16b56f6e8 \
      --header 'authorization: YOUR-API-TOKEN'

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

    {
        "acoustic_model": "assemblyai_default",
        "audio_duration": 12.0960090702948,
        "audio_url": "https://s3-us-west-2.amazonaws.com/blog.assemblyai.com/audio/8-7-2018-post/7510.mp3",
        "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": "https://postb.in/1561597007927-8767862515524",
        "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" param is 200, reflecting that our webhook was made successfully.

    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 failed, and will set the "webhook_status_code" param in the JSON response to the status code we received from your webhook URL (eg, 404, 500, 400, etc.). If for some reason we were unable to reach your webhook URL, we'll use a special status code of 999.