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.

Note!

The retry time limitation is currently set to approximately 24 hours. Over the retry limitation period the event will be retried at first with a shorter interval with up to 10 retries the first hour. After that retries will be made once an hour over the next 23 hours. So a total of 30+ retries will be made over a 24 hour period. If the event is not processed within this time frame it will be dropped.

Response Codes

A response code of 200 should always be returned for events that have been processed by the API. If the API returns a response code indicating that there is a temporary problem with the service (e.g. 429, 503 or 504), there will be 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. Any other response codes returned by the API will result in the event being removed from the queue and not retried.

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. A response code of 200 should always be returned for events that have already been handled.

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.

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,
      "warehouse_id": 2,
      "delivery_type": "add"
    }
  },
  {
    "event_id": "3b7276239c074bd1badcd87d8db76e6b",
    "event_type": "order",
    "event_date": 1629275455,
    "account_id": 94001,
    "data": {
      "eshop_id": 1,
      "order_id": 12345,
      "warehouse_id": 2,
      "order_event_type": "update",
      "order_state_changed": "closed"
    }
  }
]

User-Agent: Go-http-client/1.1
Content-Length: 661
Authorization: Basic ZXZlbnQtbGlzdGVuZXI6MTIzNDU2
Content-Type: application/json
Accept-Encoding: gzip