Skip to content

Event Format⚓︎

All events delivered through the Events API share a common base structure and follow some common rules, which are described below.

Structure⚓︎

The payload of all events consists of a metadata and data part.

Example

{
  "metadata": {
    "id": "01F1FHJ7SHQK5MGF69B8K2346E",
    "type": "VehicleStateRecorded",
    "schema_major_version": 2,
    "occurred_at": "2020-01-30T13:22:05Z",
    "flow_id": "804f2161-a15c-420f-8f21-61a15c320f68"
  },
  "data": {
      // event's data content
  }
}

metadata⚓︎

Within the metadata part of each event, you will find the following properties:

  • id uniquely identifies each event (allows you to perform duplication checks if needed).
  • type tells you what type of event it is. This is especially useful for distinguishing between multiple event types that are being published to the same event topic.
  • occurred_at is the timestamp of the event’s occurrence. Example: For all CentralLockStatusChanged events, this is the timestamp where the telematics unit detected the change of the central lock status.
  • schema_major_version is the event type’s major version (see semantic versioning).
  • flow_id can be matched with the X-Invers-Flow-ID header if the event directly results from an API call.

Some event types may define additional metadata properties. However, the above mentioned properties will be always be present in all events.

AMQP message properties⚓︎

All of the above-mentioned metadata properties and their values are also transmitted as AMQP message properties as follows:

metadata property AMQP message property
id Message ID
type Type
occurred_at Timestamp
schema_major_version Header["schema_major_version"]
flow_id Correlation ID

Depending on your use case and implementation, it might be easier and quicker to use the AMQP message properties in your consuming application rather than deserializing the payload in order to retrieve this information from the metadata part of the event. This is especially true if you would like to filter out certain events based on their event type or other criteria (see parsing events).

data⚓︎

Contains the event’s data. The content depends on the type of the event (see API reference).

Event content⚓︎

The events share many of the schemas and naming conventions of the corresponding REST APIs. This way, it is easy to use common data models for both.

JSON⚓︎

The event payloads are JSON-formatted (application/json).

Timestamps⚓︎

All timestamps are in UTC and are described in the following ISO 8601-compatible format: 2014-10-17T14:30:00Z