Skip to main content

Webhooks

Use webhooks for near-real-time delivery of change events.

For most integrations, webhooks should be the primary source of ongoing changes. Use GraphQL to bootstrap and refresh the building, floor, space, and sensor reference data needed to interpret each event.

Get started​

  1. Follow the Quickstart to register a webhook and receive your first delivery.
  2. Read Delivery and batching for the envelope, ordering, retry, and idempotency model your receiver has to handle.
  3. Use Event payloads as the field-level reference for each event type.
  4. Secure the endpoint with Securing your endpoint.
  5. Join event identifiers to names and hierarchy with Resolve event data with GraphQL.

Supported event types​

Webhook type (GraphQL)Payload TypeDelivers
OccupancyChangesOccupancyOccupancy status and headcount changes per floor space
FloorSightingsFloorSightingsAnonymous sighting coordinates per floor, per time block
SpaceSensorReadingsSpaceSensorReadingEnvironmental readings per space sensor capability

The enum you pass to addWebhook and the Type value in the delivered payload are not the same string. Switch on the payload Type when routing events.

When to use webhooks​

  • Streaming ongoing occupancy, sighting, or sensor-reading changes into another system.
  • Triggering building automation or space-availability updates on change rather than on a timer.

Use GraphQL instead for reference data, backfills, reconciliation after an outage, and analytics or historical queries.

Scope and volume​

  • A webhook receives events for your entire organisation: every building and floor you have access to. Webhooks are not filtered per building or floor, so filter downstream by FloorSpaceId/FloorId where a receiver only needs one site.
  • Plan for volume. A large portfolio can produce on the order of 1–2 million occupancy events per weekday (tens of events per second at peak). Size your receiver for this up front, and acknowledge batches quickly while processing asynchronously. Over 90% of occupancy events are headcount-only changes, so if you only need occupied/vacant state the ExcludeHeadcountChanges option reduces volume dramatically.

Test your receiver​

If your floor is in dev mode, you can generate synthetic occupancy and floor-sighting traffic. See Webhook test events.