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.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. |