Defining and using API webhooks

API Webhooks (or callbacks) can be used when a 3rd party web server needs to be notified about changes in the ERP (see Webhook definition ). A Webhook is created for a certain document type and for an event that will trigger sending of webhook to another web server by using HTTP or HTTPS protocol.

How to define a Webhook using the GUI

You can define Webhooks in menu |Settings |Company settings |API Webhooks.

To add a webhook click on the button Add new Webhook on the webhooks overview page.

	Slika 1: API webhook entry form

In the form select document type and event for which the webhook should be triggered. Enter URL address of the endpoint that will receive webhook requests each time the event will be triggered.

Processing webhooks

Webhook endpoint should be able to process HTTP(S) POST requests with JSON payload. The endpoint should be able to process multiple webhook events from the JSON payload since the ERP will optimize webhook delivery on bulk operations inside the ERP. If multiple webhooks are triggered in a short time period, the ERP will group webhook events together and send up to 500 events with a single POST request to reduce the number of network roundtrips.

The endpoint should respond with 200 OK response. The endpoint should not time out. Processing of the events should be implemented in a separate thread so that webhook handler can respond within 10 seconds of receiving the HTTP(S) request.

Webhook events are grouped based on the endpoint URL address therefore the JSON payload can contain events from multiple webhooks with different triggers and document type.

Example of webhook JSON payload

The following example shows JSON payload that will be received when we define two webhooks for the same URL endpoint. Webhooks are triggered for the SalesInvoice document type for event types document creation and issuing of the sales invoice. Both events will be triggered almost at the same time so there will be only HTTP(S) request containing JSON payload for both events.

{
       "messageID": "DA45BDA95FFB0D00B073B66A0240ABCA",
       "messageTimestamp": "2025-01-01T13:56:25",
       "signature": "ce1c99baf7b7e0b7aad646b2833313947262171cdf307d4e36c4cffd213f20e5",
       "events":
       [
               {
               "documentType": "SalesInvoice",
               "documentID": "60:12341",
               "webhookID": 1,
               "eventType": "objectCreated",
               "timestamp": "2025-01-01T13:53:00",
               "data": [{
                       "documentID": "60:4177469",
                       "documentIdBarCode": "ER$5U#1#1Q#349OP",
                       "number": "4405/01/231",
                       "status": "IssuedInvoice",
                       "city": "Maribor",
                       "businessYear": 2025,
                       "businessUnit": "01",
                       "costPosition": "SUB",
                       "warehouseCode": "0000",
                       "documentCurrency": "EUR",
                       "date": "2025-09-17",
                       ....
               }]}
               ,
               {
               "documentType": "SalesInvoice",
               "documentID": "60:4179",
               "webhookID": 3,
               "eventType": "documentIssued",
               "timestamp": "2025-01-01T13:53:03",
               "data": [{
                       "documentID": "60:4177469",
                       "documentIdBarCode": "ER$5U#1#1Q#349OP",
                       "number": "4405-01-231",
                       "status": "IssuedInvoice",
                       "city": "Maribor",
                       "businessYear": 2025,
                       ...
               }]}
       ]
}

Checking JSON payload signature

JSON payload is signed using HMAC-SHA256 signature where the organizations's web services token is used as a key for the signature.

The signature hash is calculated on string which is concatenation of messageID, messageTimestamp and the events JSON. See example of string to be signed:

DA45BDA95FFB0D00B073B66A0240ABCA
2025-01-01T13:56:25
[
               {
               "documentType": "SalesInvoice",
               "documentID": "60:12341",
               "webhookID": 1,
               "eventType": "objectCreated",
               "timestamp": "2025-01-01T13:53:00",
               "data": [{
                       "documentID": "60:4177469",
                       "documentIdBarCode": "ER$5U#1#1Q#349OP",
                       "number": "4405/01/231",
                       "status": "IssuedInvoice",
                       "city": "Maribor",
                       "businessYear": 2025,
                       "businessUnit": "01",
                       "costPosition": "SUB",
                       "warehouseCode": "0000",
                       "documentCurrency": "EUR",
                       "date": "2025-09-17",
                       ....
               }]}
               ,
               {
               "documentType": "SalesInvoice",
               "documentID": "60:4179",
               "webhookID": 3,
               "eventType": "documentIssued",
               "timestamp": "2025-01-01T13:53:03",
               "data": [{
                       "documentID": "60:4177469",
                       "documentIdBarCode": "ER$5U#1#1Q#349OP",
                       "number": "4405-01-231",
                       "status": "IssuedInvoice",
                       "city": "Maribor",
                       "businessYear": 2025,
                       ...
               }]}
]