Sitoo Events SPI

Sitoo Events SPI is used for integrations to get event callbacks (also known as "Web Hooks") from Sitoo Platform.

SPI (Service Provider Interface)

The SPI is the definition of the API required to use the service in Sitoo. Therefore, the external service needs to fully implement the API definition.

Event Processing

The events will be sent to the API in an array which can contain up to 10 items. The events are always sent in chronological order. The response should be done in a timely manner. If the response is not received within 15 seconds, the events will be put back in the queue and retries will be done subsequently. This will block any other requests until a valid response has been received or the events have been dropped due to retry time limitation.

Response Codes

A response code of 200 or 4XX (except for 429) will remove the events from the queue and proceed with the next batch. The 4XX (except for 429) return codes are considered unsolvable since the server won't accept the request.

All other response codes will have a retry mechanism where the same request will be sent for a period of time before being dropped. In this case, no other events will be sent until an acceptable response has been received, or the time limit for retries has been reached.

Event Duplicates

The service needs to be implemented to handle receiving the same event multiple times. It could occur because of network problems or other issues, leading to the event being sent again.

Authentication

Authentication of the calls is optional for the server implementing it, but highly recommended. The authentication should be done using the HTTP basic authentication mechanism. Requests to the endpoint will be done over a secure connection, adding an Authorization header to the request. Example:

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=)
Note!
Do not use the Sitoo API credentials for authenticating the call. The server implementing the SPI needs to have it's own implementation for authentication.

Public Server

The URL used for the service needs to have public access with a valid SSL certificate.

Example Request

This is an example of request body and headers sent from Sitoo.

REQUEST BODY
POST https://eventcallbacks.example.com/events
[
{
"event_id": "1fcac3cf8b164a25a713e9b086dba670",
"event_type": "warehouse-transaction",
"event_date": 1629275455,
"account_id": 94001,
"data": {
"warehouse_transaction_id": 34567,
"warehouse_id": 1,
"warehouse_external_id": "WH-51",
"transaction_type": "sales"
}
},
{
"event_id": "c6ae65025db84f6eb9393a8d6396e28a",
"event_type": "order-delivery",
"event_date": 1629275455,
"account_id": 94001,
"data": {
"eshop_id": 1,
"order_id": 12345,
"order_delivery_id": 23456,
"delivery_type": "add"
}
},
{
"event_id": "3b7276239c074bd1badcd87d8db76e6b",
"event_type": "order",
"event_date": 1629275455,
"account_id": 94001,
"data": {
"eshop_id": 1,
"order_id": 12345,
"order_event_type": "update",
"order_state_changed": "closed"
}
}
]
REQUEST HEADERS
User-Agent: Go-http-client/1.1
Content-Length: 661
Authorization: Basic ZXZlbnQtbGlzdGVuZXI6MTIzNDU2
Content-Type: application/json
Accept-Encoding: gzip