Webhooks

Background

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.

Webhook versus polling

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.

AzoraOne setup

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.

-----------------------------41184676334
Content-Disposition: form-data; name="fileID"
Content-Type: text/plain
123
-----------------------------41184676334
Content-Disposition: form-data; name="webhookUrl"
Content-Type: text/plain
https://www.yourservice.com/webhooks?yourparameter=yourvalue
-----------------------------41184676334
Content-Disposition: form-data; name="file" filename="telavox.pdf"
Content-Type: application/pdf
[file data]
-----------------------------41184676334--

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.

API setup

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.

https://webhook.azora.one
Request

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.

POST https://www.yourservice.com/webhooks?yourparameter=yourvalue&companyID=123

The body will contain a FileItem which contains the status and other information about the request. The content type will be application/json.

{
"fileID": "100",
"fileName": "invoice.pdf",
"status": "READY",
"type": "Receipt",
"subType": "A"
}

There are two possible scenarios which you will need to handle when receiving the webhook. These affect the user flow of your application.

  1. 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.

  2. 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.

Response

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.

Delays

If the first response does not return 200 OK we will resend the request 5 times with an increased delay between the requests.

  1. 10 seconds

  2. 30 seconds

  3. 60 seconds

  4. 120 seconds

  5. 300 seconds

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.

Examples

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.