Event Types

VergeSense's API allows you to subscribe to various events generated by your sensors. Supported events include:

space_report
space_availability

To subscribe to a webhook either use the API endpoint below or use the VergeSense UI in order to configure.

Webhook Authentication

VergeSense provides a variety of ways for customers to authenticate requests from VergeSense to their desired destination. Authentication is not required but some form is recommended.

Technique	Required Information	Example Header	Available in UI
Basic access	`username` `password`	`Basic: [base64(username:password)]`	Yes
Bearer Token	`token`	`Bearer: [token]`	Yes
Custom Header	Any `key:value` pair	`custom_key: custom_value`	Yes
OAuth 2.0	See here for more details	`Bearer: [token]` (after receiving token from token URL)	No

IP Address Allow List
VergeSense sends webhook requests from a known set of IP addresses. Should some form of IP address filtering be desired, contact VergeSense for more information regarding the list of IP addresses.

Custom Headers

VergeSense supports custom headers, allowing customers to define any specific headers they would like sent as part of a webhook POST request.

Destination Endpoint Expectations

VergeSense has the following expectations when interacting with a user provide endpoint:

Data will only be sent to HTTPS endpoints
Endpoints should respond with a 2xx HTTP status code
Endpoints are expected to respond within 5 seconds

If any of these conditions are not met then the request will fail. If >99% of requests fail within a 24-hour period then VergeSense will automatically disable the webhook. You will be notified of this via email with details pertaining to the top errors and will be able to correct the issue and re-enable.

Space Report Event

For this type of event, reports will be sent that aggregate all sensor data and other metadata into a single report of the most up to date information regarding a space. This is especially useful in situations where multiple sensors are required to cover a single space, for example a very large conference room. In these cases, the report data is aggregated across the individual sensor reports to provide information for the whole space in one easily consumable event.

type SpaceReportEvent = {
  // customer defined building reference ID
  building_ref_id: String,
  // customer defined floor reference ID
  floor_ref_id: String|null,
  // customer defined space reference ID
  space_ref_id: String|null,
  // VergeSense internal space identifier
  space_id: Number,
  event_type: "space_report",
  // iso8601 timestamp
  timestamp: String,
  // number of people in the space
  person_count: Number,
  // whether or not there were objects like laptops, backpacks, coats, etc. detected
  signs_of_life: Boolean,
  // whether or not motion was detected in the space
  motion_detected: Boolean|null,
  // detailed information regarding the people in the space
  people: {
    count: Number,
    // array of arrays of [x,y] coordinate pairs for each person detected by a device
    coordinates: [Array<[Number, Number]>?]
  },
  // array of device IDs that report on the space
  sensor_ids: [String],
  // present if the device supports it otherwise not present
  environment?: {
    humidity: {
      // relative humidity
      units: "RH",
      value: Number
    },
    // indoor air quality
    iaq: {
      units: "UBA",
      value: Number
    },
    // device id that reported environmental information
    sensor: String,
    temperature: {
      // celsius
      units: "C",
      value: Number
    },
    // iso8601 timestamp
    timestamp: String
  }
}

Space Availability Event

While the "Space Report" webhook will send a report every time a sensor that reports on a space has new information, the "Space Availability" webhook is used to be notified when the availability of a space has changed. The possible states for the state field are available|occupied, and passively_occupiedcan take on values such as true|false|null. The payload is an array -- one record per space that a sensor reports on.

[
  {
    "building_ref_id": "building_1",
    "floor_ref_id": "floor_4",
    "space_ref_id": "123.321",
    "space_id": 321342,
    "sensor_ids": ["VS0-123", "VS1-321"],
    "event_type": "space_availability",
    "timestamp": "2019-08-21T21:10:25Z",
    "state": "occupied",
    "passively_occupied": true
  }
]