What Is A Webhook?

Generally speaking, a webhook sends real-time information from one application to another when an event is triggered. At VergeSense, we send real-time information when these events occur:

• Space availability change: A space goes from occupied to free and vice versa 
• Space report: A motion event is triggered and new data is reported. This may include a person count change, person coordinate/distance change, or environmental data change (E105 model only). 

We have two other event types and want you to focus on the aforementioned as they provide the highest value for everyday use cases. More information on webhooks is available here.

What Use Cases Are Achieved Using Webhooks? 

VergeSense customers can benefit from webhooks to power applications and workflows that: 

1. Report on real-time space availability - such as digital kiosks or employee experience applications 

2. Plug-in with room booking systems - customers that have adopted desk or room booking tools can use VergeSense data to automate check-in & release of reservations. 

3. Single plane of glass for workplace analytics - integrations with leading Integrated  Workplace Management Software providers enabled mutual customers to visualize high-quality data from multiple data sources in a single application 

4. Custom applications - leverage webhook data to power custom applications that  report from multiple data sources

Pre-Setup Field Considerations

Event type: What type of data do they need to take action? (e.g. if the application or workflow only needs to leverage space state changes then use the space availability webhook) 

Name: You should label their webhooks so they can easily identify them later. Also, this helps VergeSense keep track of where data is going and will help prioritize future named integrations/use cases. 

Endpoint URL: Where is the data going? For the application or workflow that will consume the data from VergeSense, it will transmit to a destination first beforehand. If you don’t know this immediately, contact VergeSense or the third party that will handle the data orchestration. 

Authorization Type: Just as a badge reader provisions access to a building, in order for a data payload to reach a destination it may need to be provisioned before the “door” opens. This is a fair question to the team and/or third party that handles the data orchestration. You may need to provision via an access token or basic username/password authentication types. 

Key-Value Pairs: You will also need to ask your data provider for key-value pairs. Key-value pairs are used when static unique identifiers need to be appended to the webhook payload for appropriate processing.

Building Filter: There very well may be cases where you have different applications powering different buildings. VergeSense provides you with the flexibility to define which buildings a webhook is triggered for.

Setup

Navigate to the Settings menu and select Integrations. Scroll down to the Webhooks section and select Create New Webhook.

Once the wizard opens, you'll be able to fill out the form and necessary fields to set up your webhook.

Enable toggle - Checking the box will enable or disable the webhook

Event Type - We offer two types of information.

Space Report

Sends a report with aggregated 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, // customer defined space reference ID space_ref_id: String, 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: { // array of arrays of [x,y] coordinate pairs for each person detected by a device coordinates: [Array<[Number, Number]>?], count: Number, distances: { units: "meters", // meters apart people are from one another values: [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

Sends 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. 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", "sensor_ids": ["VS0-123", "VS1-321"], "event_type": "space_availability", "timestamp": "2019-08-21T21:10:25Z", "state": "occupied" } ]

1. Name - A unique identifier that helps you remember where the data is going. Are you sending data to iOFFICE or an internal data repository in Snowflake? Then label as such.

2. Endpoint URL - This is the endpoint that will collect the json payload.

3. Authorization Type - If your endpoint URL requires a token key or basic authentication to successfully send events, enter it here, otherwise select No Authorization.

4. Key-value pairs - If you need to append key values to the event payload, enter them here.

5. Select Save to create your webhook.

If you need to edit or delete your webhook, select Edit. The setup wizard will open and you'll be able to edit fields and/or remove the webhook from the system.

Frequently Asked Questions

Will my existing webhooks display here?

Yes, your existing webhooks are here.

I am a VergeSense partner and am trying to set up a webhook for a mutual customer, how can I do this?

If you don't have access to the account, please contact the account owner and provide them with the necessary information they need to configure the webhook.

How can I create a webhook alongside my calendar integration to auto check-in or release a room?

This feature is available for customers that have a Robin or GCal integration. If you want to enable this feature please contact your CSM. We are looking to expand this feature to other room-booking tools and calendars.

Updated May 15, 2023 16:50