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.