Skip to main content

Webhooks & Events

SpaceOS uses webhooks for event-driven communication between services and with external integrations.

How Webhooks Work​

  1. Subscribe — Register a webhook URL via the API or admin dashboard
  2. Event occurs — A booking is created, device status changes, etc.
  3. Deliver — SpaceOS sends an HTTP POST to your URL with the event payload
  4. Verify — Validate the HMAC-SHA256 signature to ensure authenticity
  5. Acknowledge — Return a 2xx response within 30 seconds

Event Categories​

CategoryEvents
Bookingbooking.created, booking.confirmed, booking.start, booking.end, booking.cancelled
Meeting Spacemeeting.status_update, space.availability_changed
Devicedevice.online, device.offline, device.action_completed
Organizationorganization.updated, member.added, member.removed

Delivery Guarantees​

  • At-least-once delivery — Events may be delivered more than once; use idempotency keys
  • Automatic retry — Failed deliveries are retried with exponential backoff
  • Delivery logs — Every attempt is logged with response status and timing
  • Deduplication — Booking metadata flags prevent duplicate processing

Webhook Payload Format​

{
  "event": "booking.start",
  "timestamp": "2025-01-15T09:45:00.000Z",
  "data": {
    "booking_id": "bk-abc123",
    "meeting_space_id": "ms-xyz789",
    "organization_id": "org-123",
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": "2025-01-15T11:00:00Z"
  }
}

Signature Verification​

Every webhook includes an HMAC-SHA256 signature in the X-Webhook-Signature header:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');

if (signature === request.headers['x-webhook-signature']) {
  // Valid webhook
}

Internal Webhooks​

ZenCore and ZenEdge communicate via internal webhooks for:

  • Booking access — booking.start at T-15 and T-0 triggers magic link issuance
  • Status sync — Scheduler posts status updates back to ZenCore
  • Device events — ZenEdge forwards device events to ZenCore

Next Steps​