Skip to main content

Webhooks — Receiving Events from ZenSpace

If you set webhook_url on the connection request, ZenSpace POSTs to that URL for two classes of events.

7.1 Transport Semantics​

  • Method: POST

  • Content-Type: application/json

  • Signature header: None. No HMAC, no shared secret. Treat the URL as a secret.

  • Retry policy: None. Non-2xx responses or timeouts are logged and dropped.

  • Ordering: not guaranteed.

7.2 Best Practices​

  1. Treat the webhook URL as a secret. Use a long, unguessable path.

  2. Respond 2xx quickly (under ~2 seconds). Do heavy work async.

  3. Be idempotent. Key on connection_id + event + booking_id.

  4. Log everything. You have no retry; reconcile against GET /api/bookings/{id} manually.

  5. Verify the payload shape. Don’t trust fields to be present.

7.3 Connection-Status Webhooks​

Fired when the admin approves, declines, or suspends your connection.

Approved payload:

{

"status": "approved",

"connection_id": "c7e8f9a0-...",

"meeting_space_id": "123e4567-...",

"zenspace_webhook": "https://api-spaceos.zenspace.io/api/v1/third-party/webhook/c7e8f9a0-..."

}

The zenspace_webhook URL is reserved for a future release and currently returns 404. Treat it as informational.

7.4 Booking-Event Webhooks​

Once your connection is approved, ZenSpace POSTs a notification when an admin modifies a booking from the ZenSpace side (not from your bridge).

event values: created, updated, cancelled

Feedback-loop protection: ZenSpace does not send webhooks for changes your bridge itself made (detected via API-key origin). You will only receive events for admin-originated changes.