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
AssemblyAI sends a
POSTrequest from a static IP address:
126.96.36.199. When you receive a webhook request from AssemblyAI, the request includes the following headers.
accept-encoding: gzip, deflate
And the request body includes the following parameters.
transcript_idfield contains the ID of the completed transcription, and the
statusfield indicates whether the transcription was completed successfully or if there was an error.
error, you can make a
GETrequest using the
transcript_idto get more information on the error.
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:
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.