Webhooks

Register webhook endpoints to receive real-time event notifications from SpaceOS.

Create Webhook

POST /api/v1/webhooks
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "organization_id": "org-123",
  "url": "https://your-app.com/webhooks/spaceos",
  "events": ["booking.created", "booking.start", "booking.end", "booking.cancelled"],
  "secret": "your-webhook-secret"
}

List Webhooks

GET /api/v1/webhooks?organization_id=org-123
Authorization: Bearer <jwt>

View Delivery Logs

GET /api/v1/webhooks/:id/deliveries
Authorization: Bearer <jwt>

Webhook Payload

{
  "event": "booking.start",
  "timestamp": "2025-01-15T09:45:00.000Z",
  "webhook_id": "wh-abc123",
  "data": {
    "booking_id": "bk-xyz789",
    "meeting_space_id": "ms-abc123",
    "organization_id": "org-123",
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": "2025-01-15T11:00:00Z",
    "organizer": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Signature Verification

Verify webhook authenticity using HMAC-SHA256:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	24 hours

After 5 failed attempts, the webhook is marked as failing and the admin is notified.

Next Steps

• Rate Limits — API rate limiting
• Webhook Event Catalog — Full event reference