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
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
And the request body includes the following parameters.
transcript_id: 5552493-16d8-42d8-8feb-c2a16b56f6e8
status: completedThe
transcript_id
field contains the ID of the completed transcription, and thestatus
field indicates whether the transcription was completed successfully or if there was an error.If the
status
returned iserror
, you can make aGET
request using thetranscript_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.