Webhooks

By configuring webhooks in the product, housed under the set of /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_reject: this event triggers to inform when a document is rejected. Includes the full payload like document_predict and document_evaluate, examples below.

In general, the payload sent by the webhooks has the following form:

{"event": "event_name", "organization": "organization_name", "data": {}}

The expected payload in “data” for both the predict and evaluate event is the same as the default document JSON.

For the other events, the resulting output will have the following form:

document_text

{"event": "document_text", "organization": "contractfit1", "data": {"id": "5e7a0daf255bf93741177061", "text": “example document text”}}

document_split

{"event": "document_split", "organization": "contractfit1", "data": {"id": "5e7a0df1800de5422a6f7776", "sections": [{"document_type": "invoice", "format": "5e20372a90d5ab65dd4a017a", "confidence": "91", "page": "0"}]}}

document_delete

{"event": "document_delete", "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:

{
"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):

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. For example, adding that to the example above:

{
"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:

{
"type": "webhook",
"events": ["document_predict"],
"target": "http://localhost:3000/alfred/document_predict",
"headers": {"Authorization": "Bearer abcdefg1234567989"}
"inbox": "abcdef123456789abcdef123"
}