EventNotification

The EventNotification object corresponds to a unique EventSubscription within the Carvoyant system. The EventNotification will be delivered to the postURL provided by the EventSubscription via an HTTP POST message whose JSON body contains the details specific to the notification type. Examples for the supported event types can be found in this documents children.

The Event model that we have implemented is based off of the Evented API Spec. This is a generic specification that helps define the transport of API events between two systems.

See the EventType page for details on the different events that can be notified.

Note

You will only be able to get notifications that have been created for your client Id. Specifically, we will look at the access token specified in the request, determine the client Id that was authorized with that access token, and only return notifications for EventSubscription s for that client Id. You do not have access to notifications for subscriptions that have been created by other client Ids.

Common Properties

Property Type Description
id Integer The internal system identifier for this notification.
accountId Integer The internal system identifier for this account.
vehicleId Integer The internal system identifier for this vehicle.
dataSetId Integer The Id of the DataSet that generated the notification.
tripId Integer The Id of the Trip that generated the notification.
subscriptionId Integer The internal system identifier for this notification’s corresponding EventSubscription.
_domain String Serves as a namespace for the event.
_type EventType The type of event notification being sent.
_name EventType The type of event notification being sent. Note that this field should be considered deprecated. It is only supported because the Evented API spec has not fully implemented the change.
_timestamp DateTime The time when the event occurred.
eventTimestamp DateTime The time when the event notification was created.
minimumTime Integer The time in minutes that will determine the minimum interval between event notification creation. If the value is less than the reporting interval of the hardware, the hardware limit will be used.
httpStatusCode Integer The status code that was returned when attempting to POST the EventNotification to the postUrl. When the EventNotification is delivered to the postUrl the value of httpStatusCode will be 0. However, a subsequent GET request on the EventNotification will provide a useful httpStatusCode value derived from the postUrl’s response.
notificationPeriod NotificationPeriod A string that represents when EventNotifications are sent from the Carvoyant system. Each EventType will define what periods are supported.

Supported Verbs

  • GET

GET

Returns one or more event notifications. By default, the first 50 results are returned.

Query Paths

  • /account/{account-id}/eventNotification/{notification-id}
  • /account/{account-id}/eventNotification/{event-type}/{notification-id}
  • /account/{account-id}/eventSubscription/{subscription-id}/eventNotification/{notification-id}
  • /account/{account-id}/eventSubscription/{subscription-id}/eventNotification/{event-type}/{notification-id}
  • /vehicle/{vehicle-id}/eventNotification/{notification-id}
  • /vehicle/{vehicle-id}/eventNotification/{event-type}/{notification-id}
  • /vehicle/{vehicle-id}/eventSubscription/{subscription-id}/eventNotification/{notification-id}
  • /vehicle/{vehicle-id}/eventSubscription/{subscription-id}/eventNotification/{event-type}/{notification-id}

Query Parameters

Parameter Description
account-id The Carvoyant identifier of the account. This is used for account level notification
vehicle-id The Carvoyant identifier of the vehicle. This could be the device serial number in the car (for example, C201200001) or it could be the internal id returned from a previous lookup. This is used for vehicle level notification
notification-id The Carvoyant identifier of the notification. If the notification-id is not specified, then all notifications available will be returned.
subscription-id The Carvoyant identifier of the subscription.
event-type Indicates the EventType of notifications to be returned.

Call Options

Sortable Yes (by timestamp)
Pageable Yes (when no notification-id is specified. Individual notification requests are not paginated)

Sample JSON Response

Note

This response only includes the properties that are common to all EventType . It is not a complete response. Refer to the EventType page for the detailed list of what properties are returned for the notification.

{
   "notifications":[
      {
         "id":315931,
         "subscriptionId":1647,
         "_domain":"carvoyant.com",
         "_type":"VEHICLEDISCONNECTED",
         "_name":"VEHICLEDISCONNECTED",
         "_timestamp":"20140912T010246+0000",
         "minimumTime":0,
         "httpStatusCode":200,
         "notificationPeriod":"INITIALSTATE",
         "dataSetId":4795420,
         "creatorClientId":"hasa2czfebhsj6XXXXXXXXXX",
         "vehicleId":123
      },
      {
         "id":315932,
         "subscriptionId":1646,
         "_domain":"carvoyant.com",
         "_type":"VEHICLECONNECTED",
         "_name":"VEHICLECONNECTED",
         "_timestamp":"20140912T010303+0000",
         "minimumTime":0,
         "httpStatusCode":200,
         "notificationPeriod":"INITIALSTATE",
         "dataSetId":4795435,
         "creatorClientId":"hasa2czfebhsj6XXXXXXXXXX",
         "vehicleId":123
      }
   ],
   "totalRecords":2
}