Using the /webhooks By configuring webhooks in the product, housed under the set of endpoints in the product/integrations endpoints with "type": "webhook", custom callback behaviour can be configured to trigger upon specific events. The available events are:
document_text: this event triggers the sending of the document text obtained by OCR
document_split: this event triggers the sending of section information for a document
document_predict: this event triggers sending all predictions made on a document
document_evaluate: this event triggers sending the final, reviewed version of a document once feedback has been received
document_delete: this event triggers sending a document id when it is deleted
document_fail: this event triggers sending a document id when a document has failed to process
In general, the payload sent by the webhooks has the following form:
...
| Code Block | ||
|---|---|---|
| ||
{"event": "document_delete", "organization": "contractfit1", "data": {"id": "5e7a0df1800de5422a6f7776"}} |
document_fail
| Code Block | ||
|---|---|---|
| ||
{"event": "document_fail", "organization": "contractfit1", "data": {"id": "5e7a0df1800de5422a6f7776"}} |
In terms of configuring webhooks, the swagger documentation shows how to create webhooks using the POST method .in /integrations:
...
At minimum, a target url or ip address and an event for which to trigger a webhook need to be configured:
| Code Block |
|---|
{
"type": "webhook",
"events": ["document_predict"],
"target": "http://localhost:3000/alfred/document_predict"
} |
Some simple examples of configured webhooks for the “document_predict" and “document_evaluate” event (these examples are used internally to couple our UI with the API):
...
Additional features:
...
Optionally, authorization headers can also be configured throught the “header” field
...
:
A custom (static) authorization (f.e. Bearer token) can be configured in the webhook, which will be sent back as header with the webhook’s POST request. This allows verification and authentication on the client’s side.
...
Upcoming extensions:
...
Retry logic with exponential backoff. In case of the webhook receiving anything besides a succes status code (200), the webhook will re-attempt it’s delivery with an exponential backoff system (2^n seconds) for a maximum of 10 attempts.
...
For example, adding that to the example above:
| Code Block |
|---|
{
"type": "webhook",
"events": ["document_predict"],
"target": "http://localhost:3000/alfred/document_predict",
"headers": {"Authorization": "Bearer abcdefg1234567989"}
} |
Additionally, we now have Inbox specific webhooks. A recent expansion allows to specifically configure webhooks per Inbox
...
, as well as pass this information along in the payload. The configuration for this will then look as follows:
| Code Block |
|---|
{
"type": "webhook",
"events": ["document_predict"],
"target": "http://localhost:3000/alfred/document_predict",
"headers": {"Authorization": "Bearer abcdefg1234567989"}
"inbox": "abcdef123456789abcdef123"
} |
| Info |
|---|
If you want to experiment with our webhooks before having everything set up on your side, https://hookbin.com/ is your friend |
Retry_backoff timings
0: immediately
1: retry_backoff * 2^0 seconds after attempt 0, so 30 seconds later in the example
2: retry_backoff* 2^1 seconds after attempt 1, so 1 minute after attempt 1 and 1'30 after initial attempt
3: retry_backoff* 2^2 seconds after attempt 2, so 2 minutes after attempt 2 and 3'30 after initial attempt
4: retry_backoff* 2^3 seconds after attempt 3, so 4 minutes after attempt 3 and 7'30 after initial attempt
5: retry_backoff* 2^4 seconds after attempt 4, so 8 minutes after attempt 4 and 15'30 after initial attempt