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 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