Skip to main content

Events

In order to make it easier to keep track of changes to the entities of a sales-channel. Events are an append-only log, similar to an audit log, where we will write new entries to whenever changes occur.

The primary goal of events is to ease tracking of asynchronous changes to entities, for example when in the background a transaction goes from the PENDING state to SUCCESS.

Currently, we only support events for changes to the status of transactions. However, in the future the list of supported events will expand.

Array
id
required
string <cuid>

The ID of the event.

eventType
required
string
Value: "TRANSACTION_STATUS_CHANGE"
createdAt
required
string or null <date-time>

Time when the event was recorded into the event log.

eventAt
required
string or null <date-time>

Time when the event became effective.

required
object

Additional details specific to transaction status change events.

[
  • {
    }
]

Fetching Events​

Events can be queried by making the following request:

List events
curl -X 'GET' "/saleschannel-services/v1/events" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $BEARER"
Prerequisites

Following roles are needed to be able to fetch events:

  • EVENT_VIEWER

See Authorization for more details about roles

Paginating​

The events-endpoint has support for additional query-parameters which give control over which rows are returned. These filters can be used to implement pagination.

For anyone adopting this endpoint to track changes, it is strongly recommended to implement pagination. As over time the list of events will grow too large to query at once.

Below we present pseudo-code to use pagination to continuously process all rows in the Events-endpoint. Here, we will use the createdAt column as our "pagination key". Initially, we will start with fetching the oldest elements and from there make our way to the newest. By continuously fetching newer messages, we can import events as they are emitted.

pagination_key = '2020-01-01T00:00:00.000Z' # Initially start with a date far in the past, or restore the pagination key from a different session

while True:
  # Fetch the next page of events
  page = http.get('/saleschannel-services/events', { "query": {
    "$limit": 100, # The amount of elements we want to fetch with each page
    "$orderBy": { "createdAt": "asc" }, # Iterating on the createdAt column in ascending direction
    "$filter": { "createdAt": { "gte": pagination_key } }, # Get a page of newer elements
  }})

  # Update our pagination key to skip all messages except the last one
  pagination_key = page[-1]

  # ... do something with the newly obtained page. Note that there is one message of overlap,
  # as the last message of previous page will be included on this page too.

  # Prevent making requests as fast as possible
  sleep(10)

The same logic can be adapted to other use-cases. For example, to iterate over all elements without waiting for newer elements by breaking the loop when a page smaller than the desired page-size is returned.

while True:
  # ... existing logic

  if len(page) < page_size:
    break