Webhook

The AzoraOne API has a feature called webhooks, which allows you to receive instant updates to certain resources within the API.

For now, webhooks can only be used to receive updates about the files resource. A webhook for this resource is highly motivated since it will enhance efficiency significantly. In order to understand why, we will try to give you a short background description:

Every time a file is uploaded to the AzoraOne API, some preprocessing is carried out on our server in order to prepare for the upcoming extraction process in your application. We highly recommend that you do not make it possible for your user to extract a document until this preprocessing has been carried out. An extraction request to the AzoraOne API before this point will result in an error message from the API.

So, in order for you to make the document available for extraction in your application, you have to find out when the preprocessing of the file is complete. One way to do it (although not recommended in production mode) would be to poll the files resource. A GET request to the files endpoint will return a status parameter; until the preprocessing is complete this parameter will have the value WAITING. When the preprocessing is complete, the value will be READY and you can make the document available for extraction in your application.

You would probably want to make the document available for extraction in your application as fast as possible. The preprocessing of the file on our server will usually take between three to ten seconds. If you were to find out whether the preprocessing is complete by polling, you would probably want to send a GET request to the files endpoint once every second until you receive status READY. Although this approach might work for testing purposes, it will not be optimal in production mode since it generates unnecessary server traffic. A much better approach would be for you to receive a POST request to your server the very instant that the preprocessing is complete, ensuring maximum speed and minimum server load. The latter approach can be obtained by the use of webhooks.

Setup

You will need a simple API in order to use AzoraOne's webhooks. The API should be able to receive the requests described below and return a proper success response to our service.

URL

You will need to supply us with the URL of your service. The URL should allow us to send a POST request to it.

http://www.yourservice.com/webhooks

The URL can contain query parameters if you would like us to forward them when sending requests.

http://www.yourservice.com/webhooks?yourparameter=yourvalue

For example, you could provide an identification string as a query parameter in the callback URL in order to be able to identify us as the sender of the request.

Request

Once the URL has been provided and you have received confirmation that the webhook feature has been activated you should be able to start receiving requests to your API.

The request will have a FileItem defined in its body with information about the status of the file. The most important aspect is to identify if the file has failed to process or is ready for extraction. The request will also contain a query parameter, a companyID, in order to identify which company that the file belongs to. The body will always be of the type application/json.

URL

http://www.yourservice.com/webhooks?companyID=12345
http://www.yourservice.com/webhooks?yourparameter=yourvalue&companyID=12345

Body

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

Webhooks for files are never batched, you will get a new update every single time a file has been processed on our servers.

Delays

If the first response does not return the correct response or reach the server we will resend the request 5 times with an increasing delay time.

  1. 10 seconds

  2. 30 seconds

  3. 60 seconds

  4. 120 seconds

  5. 300 seconds

In total, we will give your server 560 seconds to respond correctly. If all 6 requests fail the webhook for this specific file will not be resent and will be discarded. You will have to use polling in order to know the status of the file.

Response

Returning anything but a response with the status code 200 (OK) will result in the webhook being resent or, if all 5 retries have also failed, the webhook will be permanently lost. The body in the response does not matter and won’t be accounted for on our side.

Security

You can add any query parameter to your URL.

We are currently working on alternative solutions in regard to security and are open to hearing from you how you would like to secure your own API. Contact your AzoraOne API Team if you have suggestions or preferences regarding webhooks security.

AzoraOne is a product developed by Arkimera Robotics.