Handling asynchronous response (Callback URL)

Our API can be called by your services any time to get your data from many filtering options. But we all know that your needs will never exactly match what we built. Furthermore making constant calls to an external API to get data that belongs to you is not a good practice.

The callback URL process (or OutgoingURL)

So we have imagined and set-up a clean way for you to handle data coming from our systems. This is a simple callback system that will POST data to a route you specify at the creation of an endpoint or a campaign on our API.

As we love diagrams, here is the workflow for the callback process 

To summarize:

1. An HTTP request coming from your back-end or front-end sends an image
2. We receive the image and launch the analysis process
3. When the process is done and if you have set-up an outgoingUrl to the endpoint or campaign we trigger a POST request on the URL you specified with the result of the analysis.
4. You handle the data on the route you specified.

WARNING
Note that if you send an image without specifying an endpoint or campaign, you can not use the Callback URL process.

Code side

You must create a campaign or an endpoint via API or Kweeri, and specify the POST ready route that will be called each time we analyse an image for you.

A URL placeholder replacer allows you to specify the some values to be replaced when the outgoingUrl is triggered.
Here are the possible values handled by our replacer:
- {document_uid} 
- {document_name}
- {endpoint_uid}
- {endpoint_name}
- {campaign_uid}
- {campaign_name}
- {company_uid}

For example, you can set the outgoingUrl to https://myCallbackUrl/post/{endpoint_name}/{document_name} to make it easier
for you to retrieve the endpoint and the document, since the values will be replaced by the actual ones.

Endpoint

Creating an endpoint: file: body.json

    {
        "name": "testEndpoint",
        //make sure that our system has right to access to this route.
        "outgoingUrl": "https://myPostRoute.com/handlingReceiptData", 
        "dominantLanguage": "fr-FR"
    }

And the request:

http POST https://receipt.agkit.io/v2/endpoints < body.json

You should get a response like this:

HTTP/1.1 200 OK
{
    "name" : "testEndpoint", 
    "uid" : "EDEDEDE-EDEDEDE-EDEDED-EDEDED" //Save this somewhere for the next step
    [...]
}

Now each time you send an image with the following url:

http POST https://receipt.agkit.io/v2/endpoints/EDEDEDE-EDEDEDE-EDEDED-EDEDED/documents?name=veryGoodReceipt

It will make a POST request with JSON data on https://myPostRoute.com/handlingReceiptData when the process is done.

Campaign

The process is the same as endpoints, the difference is that you will also receive Rules data.

Creating a campaign:

👉 See this guide

You should get a response like this:

HTTP/1.1 200 OK
{
    "uid": "CECECECE-CECECE-CECE-CECECE", //Save this somewhere for the next step
    "rules": [...], 
    "name": "My first campaign",
    "dominantLanguage": "FR-fr" ,
    [...] //More metadata
}

Now each time you send an image with the following url

http POST https://receipt.agkit.io/v2/campaigns/CECECECE-CECECE-CECE-CECECE/documents?name=veryGoodReceipt

It will make a POST request with JSON data on https://myPostRoute.com/handlingReceiptData when the process is done.