The AzoraOne API features webhooks for receiving instant updates when files have finished preprocessing.
When a file is uploaded to the AzoraOne API, some preproccessing is required before the file can be extracted. This means that your application will need to wait until the preprocessing has finished before it can extract information from the file. The preprocessing time varies depending on the file size and its type, but typically lies around 1-3 seconds.
There are two ways of finding out if a file is ready to be extracted; polling the Get a file operation or using webhooks.
Polling vs. webhooks
Polling uses the result from the Get a file operation to indicate if the file is ready to be extracted or not. Following a successful file upload, the application will wait some amount of time, make a request to the Get a file operation and check if the status has changed from WAITING to READY. If not, the request will repeat until the status changes and the file can be extracted. This strategy is quite easy to implement, but can add unnecessary waiting times for the user. It also adds a lot of unnecessary server traffic between AzoraOne and your server.
Webhooks lets AzoraOne send your server a request once the preprocessing of the file is done. This means only one request will be sent in total and it will be sent as soon as the file is ready. Using webhooks will minimize server load and the waiting times for the user of your application.
Using webhooks requires some small modifications to the Add a file operation. It also requires a server on your side that features an API endpoint that AzoraOne can send a POST request to when preprocessing is done.
In order to receive a webhook when a file finishes preprocessing you will need to add the webhookUrl parameter to the Add a file request.
The webhookUrl parameter should contain the URL to the API endpoint that will be receiving the webhook request.
Content-Disposition: form-data; name="fileID"
Content-Disposition: form-data; name="webhookUrl"
Content-Disposition: form-data; name="file" filename="telavox.pdf"
Every request sent with a valid webhookUrl parameter will trigger a webhook to be sent when preprocessing of the file is finished. If the webhookUrl parameter is empty or missing from the request, no webhook will be sent.
In order to use webhooks you will need a simple API that can receive a POST request and return a 200 OK response.
All webhooks will be sent from the URL below. Make sure that your API allows requests from this URL.
The POST request will be sent to the URL defined in the webhookUrl in the Add a file request.
Optionally, you can add your own query parameters to the URL. The query parameter named yourparameter below is used as an example.
The URL will have an added companyID query parameter in order for you to identify which company the file belongs to.
The body will contain a FileItem which contains the status and other information about the request. The content type will be application/json.
There are two possible scenarios which you will need to handle when receiving the webhook. These affect the user flow of your application.
The status is "READY", which means that the file is ready to be extracted. You should extract the file and indicate to the user that the file was successfully extracted with AzoraOne.
The status is "ERROR" which means that the file was not preprocessed correctly and will not able to be extracted. You should indicate to the user that the file was unable to be extracted with AzoraOne.
Your endpoint should always respond with 200 OK. Returning anything but 200 OK will result in the webhook being sent again after a delay.
The body of the response does not matter but should preferably be empty.
If the first response does not return 200 OK we will resend the request 5 times with an increased delay between the requests.
If all these requests fail to respond with a 200 OK the webhook will be permanently lost and you will have to use polling to retrieve the status and other information about the file.
You can download an example of a server that can receive webhooks from AzoraOne here. The project is written in C# with the .NET 6.0 framework.
You can download an example of an AzoraOne webhook request for Postman here. If your server can read the companyID query parameter, the FileItem body and respond with a 200 OK your server is ready to receive real webhooks from AzoraOne.