Who's this integration guide for.
This integration guide is designed for the developers of booking, brokerage, aggregator and discovery platforms that would like to receive and process updates & syncs from integrated management systems.
The integration is broken down into steps and is designed to help drastically reduce integration time and development resources.
Before getting started.
If not completed yet, refer to docs on syncing data to get started and confirm your platform meets the base setup requirements with these use-cases:
- An existing user is able to securely connect to your platform from Syncaroo.
- An existing user is then able to map & connect their locations as needed from their management software to your platform.
- Your platform is able to receive webhook updates from Syncaroo.
- Your platform is authenticated and able to fetch live data updates via the Syncaroo API.
General Webhook Schema
{
connectionId: integer, // unique ID for authenticated connection
webhookType: string, // almost always 'data'
locationId: string, // your locationId from mapping
metaData: {
syncarooId: string, // unique ID for this object in Syncaroo
resourceType: string, // what kind of resource is this? Expected types 'meeting-room', 'hot-desk', 'fixed-desk', 'office'
resourceId: string, // your resourceId from mapping
attributeType: string, // the type of object that triggered this webhook. Eg 'resources', 'availability', 'locations', 'bookings'
apiUrl: string, // the direct URL to query this update for live data.
},
action: string, // Optional reference for webhook action. eg 'new', 'unmapped'
actionCallback: string, // Optional direct URL to query extra meta details about this action
hash: string, // an encrypted hash of the whole webhook object (excluding `hash`) to verify data integrity.
}
Example Webhooks
Below are a few popular examples to give you some more context into how webhooks are fired, an and the schema is used.
New resource added
Triggered when a new meeting-room (line 7) resource is added or mapped to connection 555 (line 2) for location 11980 (line 4).
Note: no resourceId (line 8), the action (line 12) & actionCallback (line 13) values.
{
connectionId: 555,
webhookType: "data",
locationId: "11980",
metaData: {
syncarooId: "61116c0bab789b6cc1feec23",
resourceType: "meeting-room",
resourceId: "",
attributeType: "resources",
apiUrl: "https://app.syncaroo.com/api/v1/555/locations/61116b1ad9fa63170734b694/resources/61116c0bab789b6cc1feec23"
},
action: "new",
actionCallback: "https://app.syncaroo.com/api/v1/555/locations/61116b1ad9fa63170734b694/resources/61116c0bab789b6cc1feec23/mapped",
hash: "..."
}
Recommended Actions:
If the attribute & resource type is critical to your supply inventory: Process immediately.
(eg meeting rooms, rates, or locations are added or removed)
If not, queue the update or drop webhook if not necessary.
Update to a previously mapped resource.
Triggered when a previously mapped meeting-room resource with id 78430 (line 8) is updated within connection 555 (line 2) for location 11980 (line 4).
{
connectionId: 555,
webhookType: "data",
locationId: "11980",
metaData: {
syncarooId: "61116c0bab789b6cc1feec23",
resourceType: "meeting-room",
resourceId: "78430",
attributeType: "resources",
apiUrl: "https://app.syncaroo.com/api/v1/555/locations/61116b1ad9fa63170734b694/resources/61116c0bab789b6cc1feec23"
},
hash: "..."
}
Recommended Actions:
If the attribute & resource type is critical to your supply inventory: Process immediately.
(eg meeting rooms, rates, or locations are added or removed)
If not, queue the update or drop webhook if not necessary.
A previously mapped resource is unmapped/removed.
Triggered when a previously mapped meeting-room resource with id 78430 (line 8) is removed from connection 555 (line 2) for location 11980 (line 4)
Note: action (line 12) value.
{
connectionId: 555,
webhookType: "data",
locationId: "11980",
metaData: {
syncarooId: "61116c0bab789b6cc1feec23",
resourceType: "meeting-room",
resourceId: "78430",
attributeType: "resources",
apiUrl: "https://app.syncaroo.com/api/v1/555/locations/61116b1ad9fa63170734b694/resources/61116c0bab789b6cc1feec23"
},
action: "unmapped",
hash: "..."
}
Recommended Actions:
If the attribute & resource type is critical to your supply inventory: Process immediately.
(eg meeting rooms, rates, or locations are added or removed)
If not, queue the update or drop webhook if not necessary.
A booking slot has been created or updated.
Triggered when a previously mapped meeting-room resource (line 7) with id 78430 (line 4) is booked at location 11980 (line 4).
Note: attributeType (line 9) value.
{
connectionId: 555,
webhookType: "data",
locationId: "11980",
metaData: {
syncarooId: "'61c18cf515e22a061cf589b1*1640124000000*1640125800000",
resourceType: "meeting-room",
resourceId: "78430",
attributeType: "bookings",
apiUrl: "https://app.syncaroo.com/api/v1/555/locations/61116b1ad9fa63170734b694/resources/6140afff1da7a718a6076cea/bookings/61c18cf515e22a061cf589b1*1640124000000*1640125800000"
},
hash: "..."
}
