Event Webhooks

Event Webhook Details

D
Written by Dave Almond
Updated over a week ago

Overview

To aid in integration with Semantik you can subscribe to certain events that occur within the system. The event details are sent via webhook to an address that you specify.

Managing Event Settings

The Semantik Public API page lists the endpoints available for managing event configuration.

Receiving Events

Event data will be sent to the configured receiver as an HTTP POST call. If the receiver responds with an HTTP status code in the range 200-299 within the timeout period the webhook call is considered successful.

The following conditions are considered failures and will be retried:

  • More than 5 redirect responses (HTTP status 301 or 308) are received from the server.

  • The receiver responds with an HTTP status code outside the 200-299 range.

  • The receiver does not respond within the timeout period of 90 seconds.

  • A network error is encountered (DNS lookup failure, network-not-available, etc.).

Failed webhook calls are retried as follows:

Retry #

Approximate Delay (from previous attempt)

1

1 second

2

4 seconds

3

12 seconds

4

45 seconds

5

2.5 minutes

If all retries fail, the event is silently discarded.

Event Body Structure

All events are sent in a standard JSON envelope:

{
"tenant": {
"id": string
},
"code": string,
"description": string,
"data": object
}

Property

Description

Example

tenant.id

ID of the tenant the event applies to.

“861fb300-9c3f-4e09-99e4-e43fc9c6c151”

code

A code which uniquely identifies the event.

“DOCUMENT_STATUS_REVIEW”

description

A human-readable description of the event. NOTE: Unlike the code property, description is for human consumption only and is subject to change without warning.

“Document requires manual review”

data

Contains detail information about the event.

See Event Types section below.

Event Types

Document Requires Manual Review

Sent when a document enters a manual review state.

code

DOCUMENT_STATUS_REVIEW

data type

DOCUMENT_IDENTIFIERS

Data Structure:

{
"type": "DOCUMENT_IDENTIFIERS",
"ingestion": {
"id": string,
"index": number,
"source": string,
},
"document": {
"id": string,
"fileName": string
}
}

Property

Description

Example

type

Always “DOCUMENT_IDENTIFIERS”

“DOCUMENT_IDENTIFIERS”

ingestion.id

ID of the ingestion containing the document.

“48c3e9d4-b2c6-4a55-9f0b-6263010c4bdf”

ingestion.index

Zero-based index of the document within the ingestion.

0

ingestion.source

Source of ingestion.

  • email - document was sent in as an e-mail attachment

  • api - document was uploaded via the document upload API

“email”

document.id

ID assigned to the document by Semantik.

“f63eb034-a190-4fb0-8848-f7c2648c0c3a”

document.fileName

The original physical file name of the document.

“october-invoices.pdf”

Example webhook body:

{
"tenant": {
"id": “861fb300-9c3f-4e09-99e4-e43fc9c6c151”
},
"code": “DOCUMENT_STATUS_REVIEW”,
"description": “Document requires manual review”,
"data": {
"type": "DOCUMENT_IDENTIFIERS",
"ingestion": {
"id": “48c3e9d4-b2c6-4a55-9f0b-6263010c4bdf”,
"index": 0,
"source": "email",
};
document: {
"id": “f63eb034-a190-4fb0-8848-f7c2648c0c3a”,
"fileName": “october-invoices.pdf”
}
}
}

Headers

The following special headers will be included with every call:

Header

Description

X-Request-Id

Uniquely identifies the event - the value of this header remains consistent even if the HTTP call is retried due to a failure.

NOTE: While unlikely, there is a possibility that duplicate events may be sent with different X-Request-Id values.

X-Request-Number

The attempt number. This will be “1” for the initial request and will be incremented by one each time the call is retried.

Did this answer your question?