Skip to main content

Asynchronous Invocation details

All asynchronous calls receive a JSON payload jobTicket as means of tracking the status of the job. The jobStatus tracking the request will change from "created" to "running","failed" or "completed" as your request is being processed in the background. The initial jobTicket response will be 202 Accepted as per our API Reference.

Asynchronous result​

The $._links.self.url resource will point to a presigned url location where your jobTicket status updates will arrive. Keep polling this location at regular intervals until the status of the job becomes "completed". Your data will arrive in the Content-Type that was requested in the original request via the export format you provided. Once the request handling has completed in the background, your data arrives in the $._links.result.url presigned location and your final poll of the result location will return it.

flowchart image

Callback notification​

When an asynchronous API receives a request, it can start processing it and return an initialized job ticket immediately, without waiting for the processing to complete. The API can then notify the client when the processing is complete, using a callback request call.

The callback parameter allows the client to provide an information about request to be called when the APIs processing is complete. This way, you do not need to continuously poll the API to check if the processing is complete. Instead, the API can send the callback request when the processing is complete. All you need to do is to poll job ticket once again to get the full ticket info including result url.

flowchart image

Schema of callback template​

You can provide a URL template that the API will use to send callback requests. This URL template can include different parameters, depending on the type of callback. For all asynchronous operations, the API provides a jobStatus and traceId template parameters, which developers can use in their callback URL template.

To use the jobStatus and parameter, developers can include it in their callback URL template using double curly braces, like so: https://callbackurl.com?status={{jobStatus}}&traceId={{traceId}}. When the API sends a callback request, it will replace the {{jobStatus}} and {{traceId}} placeholder with the actual status of the job being performed. This allows developers to receive real-time updates on the status of their API requests.

info

It is recommended that a unique reference be included to correlate the callback with the API request that was initiated. This unique reference should be a single-use and unguessable UUID identifier unique to the API call. To include this reference, you have the option to place it on the path or in the query parameters. It is advised to place the identifier in the query parameters for best practice. For example https://callbackurl.com?jobId=96a7a523-cc9c-4631-a3ea-1b17b2983527?status={{jobStatus}}

Callback URL requirements​

If you want to use a callback URL as a parameter, there are several requirements that the callback URL should meet:

  • HTTPS only: The callback URL must be a valid URL that can be accessed by the API and use the https protocol.

  • Accessible from the internet: The callback URL must be accessible from the internet, as the API will need to send HTTPS requests to it. The callback URL should not be behind a firewall or other network restrictions that would prevent the API from accessing it.

  • No custom ports: callback URLs should not use non-standard or custom port numbers. (only HTTPS 443 port will be used)

By following these requirements, the API can ensure that the callback URL is a reliable endpoint for handling callback requests

Additional Headers​

To enhance the functionality of our callback service, we are adding some additional headers to the callback requests. These headers will provide valuable information and improve the overall integration experience.

The following additional headers will be included in the callback requests:

  • Trace-Id: tracking id of operation

  • User-Agent: Our unique agent identifier (OrgvueAPI/1.0)

Please ensure that your systems are capable of processing these additional headers