Using OfficeMaps Webhooks

OfficeMaps Webhook Developer Guide

This guide explains how to receive and validate webhook events from OfficeMaps.

Introduction

OfficeMaps webhooks allow your application to receive real-time notifications when events occur in your workspace management system. When an event happens (e.g., a reservation is created or a user checks in), OfficeMaps sends an HTTP POST request to your configured endpoint with the event data.

Security

All webhook payloads are signed using HMAC-SHA256. The signature is included in the X-Signature HTTP header, allowing you to verify that the request originated from OfficeMaps and hasn't been tampered with.

Supported Events

Event Type	Description
`ReservationCreated`	A new desk or room reservation was created
`ReservationCancelled`	A reservation was cancelled
`CheckedIn`	A user checked into a workspace
`CheckedOut`	A user checked out of a workspace
`PersonStatusChanged`	A user's work status changed (e.g., In Office, Remote, Non Work Day)

Setting Up Webhooks

Webhooks are configured in the OfficeMaps admin portal. Navigate to Administration > Settings > Webhooks to access the webhook management page.

Webhook List

The webhooks page displays all configured webhooks in a table format:

Column	Description
Active	Checkbox indicating whether the webhook is enabled
Name	The descriptive name for the webhook
Webhook URL	The endpoint URL that receives webhook events
Created	Date and time when the webhook was created

From this view you can:

Click the + Add button to create a new webhook
Click the edit icon (pencil) on any row to modify or delete a webhook
Click Test Webhook to send a test payload to your endpoint

Adding a New Webhook

Click the + Add button to open the webhook configuration panel:

Configure the following fields:

Field	Required	Description
Name	Yes	A descriptive name to identify this webhook. Must be unique within your organization. (1-100 characters)
Webhook URL	Yes	The endpoint URL that will receive webhook events. Must use HTTPS. (Max 2048 characters)
Secret Key	Yes	The HMAC signing key used to validate webhook signatures. Click Generate to create a random key, or enter your own. Store this securely as it's required for signature validation. (16-256 characters)
Events to Send	Yes	Select which event types should trigger this webhook. At least one event must be selected.
Active	No	Enable or disable the webhook. Defaults to enabled.

Click Save to create the webhook.

Editing and Deleting Webhooks

To edit an existing webhook, click the edit icon (pencil) on the webhook row. The same configuration panel will open, allowing you to modify any settings.

To delete a webhook, open the edit panel and use the delete option.

Webhook Payload Structure

HTTP Request

OfficeMaps sends webhooks as HTTP POST requests with the following characteristics:

Property	Value
Method	`POST`
Content-Type	`application/json`
X-Signature	HMAC-SHA256 signature (lowercase hexadecimal)

Payload Wrapper

All webhook payloads follow this structure:

{
  "id": "string",
  "type": "string",
  "timestamp": "string",
  "data": { }
}

Field	Type	Description
`id`	string	Unique event identifier (UUID)
`type`	string	Event type name (e.g., `ReservationCreated`, `CheckedIn`)
`timestamp`	string	ISO 8601 timestamp when the event occurred (UTC)
`data`	object	Event-specific payload data

Event Types

ReservationCreated

Triggered when a new desk or room reservation is created.

Data Fields

Field	Type	Description
`personAssetId`	string (UUID)	Unique identifier for the person-asset link
`personId`	string (UUID)	ID of the person making the reservation
`assetId`	string (UUID)	ID of the reserved asset (desk/room)
`assetName`	string	Name of the asset
`reservationStartTimeUtc`	string (ISO 8601)	Reservation start time in UTC
`reservationEndTimeUtc`	string (ISO 8601)	Reservation end time in UTC
`reservationStartTimeLocal`	string (ISO 8601)	Reservation start time in local timezone
`reservationEndTimeLocal`	string (ISO 8601)	Reservation end time in local timezone
`timezoneIana`	string	IANA timezone identifier (e.g., `Australia/Sydney`)
`siteLocationId`	string (UUID)	Site/building ID
`siteLocationName`	string	Site/building name
`siteLevelId`	string (UUID)	Floor/level ID
`siteLevelName`	string	Floor/level name
`city`	string	City
`region`	string	Region/State
`country`	string	Country
`floorName`	string	Floor name
`neighbourhoodName`	string	Neighbourhood/zone name
`personEmail`	string	Person's email address
`personFullName`	string	Person's full name
`reservationIsToday`	boolean	Whether the reservation is for today

ReservationCancelled

Triggered when a reservation is cancelled.

Data Fields

Field	Type	Description
`personAssetId`	string (UUID)	Unique identifier for the person-asset link
`personId`	string (UUID)	ID of the person who made the reservation
`assetId`	string (UUID)	ID of the reserved asset
`assetName`	string	Name of the asset
`reservationStartTimeUtc`	string (ISO 8601)	Original start time in UTC
`reservationEndTimeUtc`	string (ISO 8601)	Original end time in UTC
`reservationStartTimeLocal`	string (ISO 8601)	Original start time in local timezone
`reservationEndTimeLocal`	string (ISO 8601)	Original end time in local timezone
`timezoneIana`	string	IANA timezone identifier
`siteLevelName`	string	Floor/level name
`floorName`	string	Floor name
`neighbourhoodName`	string	Neighbourhood/zone name
`personEmail`	string	Person's email address
`personFullName`	string	Person's full name
`cancelledAt`	string (ISO 8601)	When the reservation was cancelled (UTC)
`cancelledBy`	string	Who cancelled the reservation

CheckedIn

Triggered when a user checks into an asset.

Data Fields

Field	Type	Description
`personAssetId`	string (UUID)	Unique identifier for the person-asset link
`personId`	string (UUID)	ID of the person checking in
`assetId`	string (UUID)	ID of the asset
`assetName`	string	Name of the asset
`checkInTimeUtc`	string (ISO 8601)	Check-in time in UTC
`checkInTimeLocal`	string (ISO 8601)	Check-in time in local timezone
`expectedCheckOutTimeUtc`	string (ISO 8601)	Expected check-out time in UTC
`expectedCheckOutTimeLocal`	string (ISO 8601)	Expected check-out time in local timezone
`timezoneIana`	string	IANA timezone identifier
`timezoneDisplayName`	string	Human-readable timezone name
`siteLocationId`	string (UUID)	Site/building ID
`siteLocationName`	string	Site/building name
`siteLevelId`	string (UUID)	Floor/level ID
`siteLevelName`	string	Floor/level name
`city`	string	City
`region`	string	Region/State
`country`	string	Country
`personEmail`	string	Person's email address
`personFullName`	string	Person's full name
`firstName`	string	Person's first name
`lastName`	string	Person's last name
`fromReservation`	boolean	Whether check-in was from a prior reservation

CheckedOut

Triggered when a user checks out of an asset.

Data Fields

Field	Type	Description

Field	Type	Description
`personAssetId`	string (UUID)	Unique identifier for the person-asset link
`personId`	string (UUID)	ID of the person checking out
`assetId`	string (UUID)	ID of the asset
`assetName`	string	Name of the asset
`checkOutTimeUtc`	string (ISO 8601)	Check-out time in UTC
`checkOutTimeLocal`	string (ISO 8601)	Check-out time in local timezone
`checkInTimeUtc`	string (ISO 8601)	Original check-in time in UTC
`checkInTimeLocal`	string (ISO 8601)	Original check-in time in local timezone
`timezoneIana`	string	IANA timezone identifier
`timezoneDisplayName`	string	Human-readable timezone name
`siteLocationId`	string (UUID)	Site/building ID
`siteLocationName`	string	Site/building name
`siteLevelId`	string (UUID)	Floor/level ID
`siteLevelName`	string	Floor/level name
`city`	string	City
`region`	string	Region/State
`country`	string	Country
`personEmail`	string	Person's email address
`personFullName`	string	Person's full name
`firstName`	string	Person's first name
`lastName`	string	Person's last name

PersonStatusChanged

Triggered when a user's work status changes.

Related Articles
Using the OfficeMaps API
This guide provides comprehensive information about our API services. Our RESTful API service provides general information and details for adding, updating and deleting a Person within OfficeMaps, as well as performing searches. We provide detailed ...
Using a Field in AD for Desk Allocation during OfficeMaps Sync
OfficeMaps has an AD Sync process to add users and associated properties from AD. Information about this is available in the article Sync People from AD. As part of this function, Administrators can specify a field in AD that is used to assign each ...
OfficeMaps Supported Browsers
OfficeMaps supports Safari 13+ and the current versions of Firefox, Chrome, and Microsoft Edge. Please note: Legacy Edge is no longer supported. For more information about Legacy Edge, please consult the following article from ...
Can't Log In to OfficeMaps?
Can't Log in with Microsoft or Google Authentication If you can't log in to OfficeMaps using Microsoft or Google authentication methods, please talk with one of your OfficeMaps Administrators to confirm that you have been added to your organisation's ...
How To Use the OfficeMaps Mobile App
Introduction Video &amp;amp;amp;amp;amp;amp;amp;amp;lt;br&amp;amp;amp;amp;amp;amp;amp;amp;gt; Signing In To start the app, open the program and when prompted, log in using your method of choice. Choosing an App to open OfficeMaps with When ...

Using OfficeMaps Webhooks

Using OfficeMaps Webhooks

OfficeMaps Webhook Developer Guide

Introduction

Security

Supported Events

Setting Up Webhooks

Webhook List

Adding a New Webhook

Editing and Deleting Webhooks

Webhook Payload Structure

HTTP Request

Payload Wrapper

Event Types

ReservationCreated

Data Fields

ReservationCancelled

Data Fields

CheckedIn

Data Fields

CheckedOut

Data Fields

PersonStatusChanged

Related Articles

Using the OfficeMaps API

Using a Field in AD for Desk Allocation during OfficeMaps Sync

OfficeMaps Supported Browsers

Can't Log In to OfficeMaps?

How To Use the OfficeMaps Mobile App