Events

In Sharetribe, events represent changes in marketplace data resources such as listings, users and transactions. An event captures a single change in marketplace data, e.g. a user being created or a listing being updated. Events can be further analyzed to interpret them as logical actions such as a listing being published, a message being sent or a user having changed their email address by looking into what were the changed data fields.

Events serve two main purposes:

1. To allow (admin) users to observe changes in marketplace data for auditing purposes. For example, what is the history of all changes for a particular listing.
2. To allow programmatically reacting to changes and logical actions in a marketplace.

Allowing programs to observe and react to changes enables efficiently solving use cases such as synchronizing changes in marketplace data into external places, e.g. a CRM, a spreadsheet or a calendar. It also allows programs to react to logical actions as part of the marketplace flows. For example, setting a field in user metadata can trigger an integration to publish the user's listings. Using events makes it possible to cover many of the use cases where other applications use webhooks.

Currently, Sharetribe exposes events by allowing them to be queried via the Integration API or viewed via Sharetribe CLI. Integration API supports implementing efficient polling where only events that have happened since last poll query are returned. This makes it possible to keep the polling interval short enough to react to events shortly after they occur.

Sharetribe does not retain event data forever. Sharetribe maintains a history of all marketplace events for 90 days in live marketplaces and for 7 days in dev and test marketplaces.

Event data

The event object contains data about the event itself, as well as about the Sharetribe resource which the event is about (listing, user, message, etc), including how the resource changed.

The exact shape of the event data differ, depending on which means it is accessed with, but the information contained is the same, regardless.

Event attributes

Each event has the following attributes:

Note: these attributes are not necessarily top-level keys. Event object data structure depends on event's data format.

Event sequence IDs

The event sequence IDs are guaranteed to uniquely identify an event. They are also strictly increasing, meaning that events that happen later always have larger sequence ID values than those that happened before them.

These properties make the event sequence IDs the most accurate way to keep track of which events have been already seen or processed in an application. The query interface supports requesting events that have happened after the given sequence ID, making the sequence ID a perfect tool for loading subsequent events in comparison to a known ID. When querying events synchronously (e.g. via the Integration API or Sharetribe CLI), events are always returned in order of their sequence IDs.

Note that, in contrast to sequence IDs, there can be multiple events that have the exact same createdAt timestamp, so applications should not use the timestamp as a strict criteria to determining event ordering or to decide which events are processed and which are not.

Event data formats

There are two data formats for events: native and Integration API event data formats.

When accessed via the Integration API, the event and associated resource data is formatted in the same way all Integration API resources are (with id, type top-level attributes and with relationships object containing the IDs of related resources). On the other hand, if the event is viewed via Sharetribe CLI, the event and resource data is not normalized. Instead, it is inlined in a simplified form. We will refer to this as native event data format.

The Integration API event data format differs from the native one as follows:

• The event object itself is structured as an API resource (with id, type and attributes keys)
• The resource object is structured itself as an Integration API resource with id, attributes and optional relationships keys, each containing the corresponding portion of resource data
• The value of relationships attributes follows the same format as relationships normally do in the Integration API

In both formats, the previousValues object always has the same shape as the resource object.

Here are two abbreviated examples (assuming that listing's title is updated):

Native event data format

{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
  // other event keys: "eventType", "sequenceId", "createdAt", ...
  "resource": {
    "id": "5bbb2f6f-568f-470a-9949-a655e3f6ac46",
    ...
    "title": "Listing title",
    "author": {"id": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a"},
    ...
  },
  "previousValues": {
    "title": "old title"
  }
}

Integration API event data format

{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
  "type": "event",
  "attributes": {
    // other event keys: "eventType", "sequenceId", "createdAt", ...
    "resource": {
      "id": "5bbb2f6f-568f-470a-9949-a655e3f6ac46",
      "type": "listing",
      "attributes": {
        "title": "Listing title",
        ...
      },
      "relationships": {
        "author": {"data": {"id": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a", "type": "user"}},
        ...
      }
    },
    "previousValues": {
      "attributes": {
        "title": "old title"
      }
    }
  }
}

Resource data and previous values

The following example event data is for a listing/updated event produced as a result of an API call in the Marketplace API. The data is in native format and its previousValues field indicate that the following occurred:

1. The listing title was updated
2. The listing availabilityPlan was updated
3. The address key in the listing's publicData was updated
4. The rules key was added to the listing's publicData
5. The set of listing images was updated, where 2 new images were added and one was removed

For examples of the Integration API event data format, see the Integration API reference.

{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
  "eventType": "listing/updated",
  "sequenceId": 12345678,
  "createdAt": "2020-11-27T12:30:02.000Z",
  "marketplaceId": "9deec37c-b59c-4884-8f60-e4944335c327",
  "source": "source/marketplace-api",
  "resourceId": "5bbb2f6f-568f-470a-9949-a655e3f6ac46",
  "resourceType": "listing",
  "resource": {
    "id": "5bbb2f6f-568f-470a-9949-a655e3f6ac46",
    "title": "Peugeot eT101",
    "description": "7-speed Hybrid",
    "deleted": false,
    "geolocation": {
      "lat": 40.64542,
      "lng": -74.08508
    },
    "createdAt": "2018-03-23T08:40:24.443Z",
    "state": "published",
    "availabilityPlan": {
      "type": "availability-plan/day",
      "entries": [
        {
          "dayOfWeek": "mon",
          "seats": 1
        },
        {
          "dayOfWeek": "tue",
          "seats": 2
        }
      ]
    },
    "privateData": {
      "externalServiceId": "abcd-service-id-1234"
    },
    "publicData": {
      "address": {
        "city": "New York",
        "country": "USA",
        "state": "NY",
        "street": "230 Hamilton Ave"
      },
      "categoryLevel1": "road",
      "gears": 22,
      "rules": "This is a nice, bike! Please, be careful with it."
    },
    "metadata": {
      "promoted": true
    },
    "price": {
      "amount": 1590,
      "currency": "USD"
    },
    "author": { "id": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a" },
    "marketplace": { "id": "9deec37c-b59c-4884-8f60-e4944335c327" },
    "images": [
      { "id": "209a25aa-e7cf-4967-89c3-0f09b2d482ff" },
      { "id": "98e11f3b-ea22-4b1b-8549-e543ae241133" },
      { "id": "ee1a647a-a751-43c7-90a4-48e94654f016" }
    ]
  },
  "previousValues": {
    "title": "old title",
    "availabilityPlan": {
      "type": "availability-plan/day",
      "entries": [
        {
          "dayOfWeek": "mon",
          "seats": 1
        }
      ]
    },
    "publicData": {
      "address": {
        "city": "New York",
        "country": "USA",
        "state": "NY",
        "street": "222 Hamilton Ave"
      },
      "rules": null
    },
    "images": [
      { "id": "98e11f3b-ea22-4b1b-8549-e543ae241133" },
      { "id": "d12b8ebc-4df8-4bd0-9231-2f05691831a4" }
    ]
  },
  "auditData": {
    "userId": "5cf4c0eb-513f-419b-a8be-bdb6c14be10a",
    "adminId": null,
    "clientId": "69ea8198-201c-48c4-a3bb-78b38e4059b0",
    "requestId": "4b66e510-22cb-47ca-953f-8a8377af2ed0"
  }
}

For all event types, except all */deleted events, the resource attribute of the event contains the full data for the corresponding API resource after the event. The resource object contains keys corresponding to the attributes that the Integration API resource has, including it's id. For list of those attributes, see the Integration API reference for each resource type (e.g. user, listing, etc).

In addition, when the resource has one or more 1-to-1 relationships with other Integration API resources (for instance, listing author or user profileImage), the resource object also contains keys with the same names as these relationships. The corresponding values are objects with single key id and value the ID of the related resource.

However, generally 1-to-many relationships are not included in the resource data, with one notable exception: the images relationship of listing resources is always included.

Note that the event data is immutable. This means that if a new attribute or relationship is added to some Integration API resource, older events for that resource type will not include data about that attribute or relationship.

The previousValues attribute holds an object describing the attributes and/or relationships of the resource prior to the event, subject to the following rules:

• Only the attributes or relationships affected in the event are included, i.e. the previousValues holds a subset of a resource data that describe the difference between the resource before and after the event.
• Resource attribute and relationship values are given in their entirety, including when the value is some nested object or array (such as the listing's availabilityPlan or transaction's lineItems, for instance).
• If an attribute that did not have a value is updated, it will be present with null value in the previousValues.
• Extended data attributes (such as user profile's publicData, listing metadata, etc) are treated as collection of key-value pairs and the difference computation treats each top-level extended data key separately:
  • If a key that did not exist in the extended data was added, the key will be given with null value in the previousValues object.
  • If a key had different value or was removed, the entire previous value is given in the previousValues object, including when the value is a nested data structure.

Note that for all */deleted events, some of the resources' attributes may occasionally have null values in the previousValues object, due to stricter data deletion requirements.

Event sources

The following table lists all possible event sources:

Supported event types

The currently supported event types and their corresponding Integration API resource types are:

The event type follows the format RESOURCE_TYPE/EVENT_SUBTYPE.

New event types may be added at any moment. Make sure your integration handles event types not given in this list gracefully (by ignoring them, for instance).

Note that some event types can occur even though there is currently no support for the corresponding functionality in the Sharetribe APIs or Sharetribe Console. Typically this can happen when the event was caused internally by an administrative action of the Sharetribe team, in which case the source of the event would be source/admin.

Transaction process actions and booking, stock reservation and review events

In Sharetribe, bookings, stock reservations and reviews are primarily managed through the transaction process using the booking-, stock reservations- and review-related actions. Sharetribe emits events separately when each of these actions takes effect, even if multiple actions occur within the same transaction transition. For instance, if a transition includes both :action/create-pending-booking and :action/accept-booking, Sharetribe generates at least three events as a result. First, there is a :booking/created event, followed by a :booking/updated event reflecting the state change of the booking and finally a :transaction/initialized or a :transaction/transitioned event for the transaction itself.

Note that this does not apply to the :transaction/* events and the actions that manipulate the transaction data itself (such as :action/privileged-set-line-items). For the transaction resource itself, there is a single event emitted that corresponds to the entire transition. The corresponding previousValues for the transaction will reflect data before the transition.

Further reading

• Integration API reference for events
• Using Sharetribe CLI to view event data
• Reacting to events how-to guide
• A full example Integration API application is available in the Integration API examples repository