Overview

The API routes provided by the Event Service work in concert to provide both access to the historical events for a Device or Vehicle as well as web-hooks for your App to receive immediate notification when an event occurs.

The normal life-cycle of working with Event Service is:

  • Create a Subscription for a particular event type for a device or vehicle
  • That event occurs for that device/vehicle
  • An event is created
  • Event Service looks for all Subscriptions for which this Event qualifies
  • A Notification is created that contains all the relevant information
  • The Notification is POSTed to the URL listed in the Subscription
  • Links within the Notification allow the App to explore the related information directly

Event Types

There are several types of events that the platform will track on a device-by-device basis. These include:

  • startup
  • shutdown
  • rule-enter
  • rule-leave
  • dtc-on
  • dtc-off
  • collision
  • trip-started
  • trip-orphaned
  • trip-stopped
  • trip-completed
  • distance-trigger

Objects

Almost all events occur in the context of a higher-level object. For example, startup and shutdown events occur in relation to a given Vehicle, rule-enter and rule-leave events occur in relation to a given Rule. This information is available as part of the event object property. Additionally, subscriptions can specifically reference a given object. For example, a subscription to startup events can optionally reference a particular Vehicle; in this way, an App will only be notified of startups where the Device is attached to a particular Vehicle.

NOTE: Subscriptions for event types rule-enter, rule-leave, or rule-* must reference a single Rule. When creating the subscription, the Rule is checked to ensure that it belongs to this particular device.