Receiving live updates

How webhooks work

• Webhooks are a way to notify you when certain events happen in the Stonal platform.
• It works by calling an HTTP endpoint of your choice on your end when an event occurs.
• They are currently only available for events related to documents.
• They cover all changes to documents, including creation, update and deletion, and are triggered for manual changes as well as automated ones (e.g. OCR, AI classification, etc).

How to use webhooks

1. You register a webhook endpoint
2. When a document changes in your organization, Stonal sends an HTTP POST request with a JSON payload to your endpoint
3. Your endpoint processes the notification and responds with a 200 OK status code

Registering a webhook

Webhooks are registered per organization by contacting the Stonal support team.

We will do better

We will allow to register webhooks directly from the platform in the future.

Events

The only events currently supported are around the documents lifecycle: creation, update and deletion of documents.

Document Created / Updated

This event is triggered when a document is created or updated. The two operations have exactly the same document payload.

Payload

{
    "organizationCode": "SAMPLE_ORG",
    "type": "document_change",
    "operation": "create",
    "document": {
        "id": "efb614e6-f1b9-4829-acc4-2c8e26ab909a",
        "name": "test.pdf",
        "type": "application/pdf",
        "metadata": {
            "KEY_1": "VALUE_1",
            "KEY_2": "VALUE_2"
        }
    }
}

Field Description

Field	Description
organizationCode	The unique identifier for your organization in Stonal
type	The type of event, in this case document_change
operation	The operation performed, in this case create or update
document.id	The unique identifier of the created document
document.name	The filename of the document
document.type	The MIME type of the document
document.metadata	Custom metadata key-value pairs associated with the document

Document Deleted

This event is triggered when a document is deleted.

Payload

{
    "organizationCode": "SAMPLE_ORG",
    "type": "document_change",
    "operation": "delete",
    "document": {
        "id": "efb614e6-f1b9-4829-acc4-2c8e26ab909a"
    }
}

Server implementation

Your endpoint should respond with a 200 OK status code to the webhook request. If it does not, the webhook will be retried up to 3 times.

Notes

Number of queued payloads

There is no limit on the number of queued payloads that can be transmitted to you. They are currently sent sequentially per organization, but this might change in the future.