# Guide to Spacebring Webhooks: Features and Best Practices

[Spacebring](https://www.spacebring.com) runs coworking and flexible-workspace operations: members and companies, room and desk bookings, events and tickets, a shop, subscriptions, invoices and visitor check-in. Its webhooks, delivered through Svix, let your own systems react to those changes, for example to sync bookings into a calendar or tell a host their visitor has arrived.

Spacebring's catalogue is broad but its payload documentation is thin. This guide lists the 32 events, explains what is and isn't known about identifying them, and covers setup and Svix verification.

## What are Spacebring webhooks?

Spacebring webhooks are part of the **API & webhooks add-on**. The network owner registers an endpoint in the network settings, chooses events, and Spacebring sends each matching change as a JSON `POST` signed with Svix's `svix-id`, `svix-timestamp` and `svix-signature` headers. Spacebring's [webhooks page](https://www.spacebring.com/docs/webhooks) links an event catalogue, and its [verifying page](https://www.spacebring.com/docs/webhooks/verifying) prints the signature scheme.

Most event schemas in the catalogue have a top-level `type` string next to one resource object named for the domain, such as `booking`, `company`, `event`, `ticket`, `membership`, `order` or `application`. The catalogue never shows what `type` contains, though; its generated examples just say "some string".

## Spacebring webhook features

| Feature | Details |
| --- | --- |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `svix-signature` |
| Body | JSON |
| Event routing | Body field `type` |
| Delivery platform | Svix |
| Availability | API & webhooks add-on |
| Who can configure | The network owner |
| Configuration | **Network settings > Developers > Webhooks** |
| Secret | `whsec_`, on the webhooks page |
| Success | Any `2xx` |
| Redelivery | Same `svix-id` |
| Retries, timeout, disabling | Not stated |

## Events and payloads

The ones most workspaces start with:

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `booking.created` | A booking is made | Sync to calendars, notify staff |
| `booking.updated` | A booking changes | Update calendars |
| `booking.deleted` | A booking is deleted | Free the resource |
| `booking.paid` | A booking is paid | Release access, mark paid |
| `membership.created` | A membership is created | Provision access |
| `membership.invited` | A member is invited | Track onboarding |
| `company.created` | A company is created | Create the account in your CRM |
| `shop.order.created` | A shop order is placed | Fulfilment |
| `shop.order.paid` | A shop order is paid | Confirm fulfilment |
| `subscription.purchased` | A subscription is purchased | Provision plan benefits |
| `invoice.issued` | An invoice is issued | Accounting sync |
| `visitors.visit.checked_in` | A visitor checks in | Notify the host |
| `support.ticket.created` | A support ticket is created | Route to a helpdesk |

The full documented list, which may grow:

* **Benefit:** `benefit.application.created`
* **Booking:** `booking.created`, `booking.deleted`, `booking.paid`, `booking.updated`
* **Company:** `company.created`, `company.deleted`
* **Event:** `event.canceled`, `event.created`, `event.deleted`, `event.updated`, `event.ticket.created`, `event.ticket.paid`
* **Invoice:** `invoice.issued`
* **Location:** `location.created`, `location.deleted`, `location.updated`
* **Membership:** `membership.created`, `membership.invited`
* **Resource:** `resource.created`, `resource.deleted`, `resource.updated`
* **Shop:** `shop.order.created`, `shop.order.paid`
* **Subscription:** `subscription.created`, `subscription.deleted`, `subscription.purchased`, `subscription.updated`
* **Support:** `support.ticket.created`
* **Visitors:** `visitors.request.approved`, `visitors.visit.checked_in`, `visitors.visit.checked_out`

What the catalogue shows about the bodies:

* Most have `type` plus a resource object, but the value of `type` is undocumented.
* `subscription.*` bodies are the bare subscription object, with no `type` and no wrapper key.
* `visitors.*` bodies carry only `visit`, with no `type`.
* `location.*`, `resource.*` and `invoice.issued` have no schema.

Svix's headers don't carry the event type either. Capture a few real deliveries before you write routing logic.

## Setting up Spacebring webhooks

You need the API & webhooks add-on and owner access to the network.

1. Deploy an endpoint that accepts `POST` and answers `2xx`.
2. In Spacebring, click the **(...)** menu next to your network name in the left panel.
3. Go to **Network settings > Developers > Webhooks**.
4. Add your URL, for example `https://example.com/webhooks/spacebring`, and choose events. `booking.created`, `booking.paid`, `membership.created`, `shop.order.paid` and `subscription.purchased` make a reasonable first set.
5. Copy the `whsec_` signing secret from the same page into `SPACEBRING_WEBHOOK_SECRET`. Use this value, not an API key.

Then make a test booking and look at what arrives. The [Hookdeck CLI](/docs/cli) gives you a public URL that forwards to your machine:

```bash
npx hookdeck-cli listen 3000 spacebring --path /webhooks/spacebring

```

**With Hookdeck.** Register the URL of a **Spacebring** source and paste the webhooks page's secret into it. The source reads the `svix-*` headers, with `webhook-*` as a fallback. Spacebring receives `200` for every `POST`, and a request that fails the signature check is kept in Hookdeck as a failed verification instead of being delivered. Any method other than `POST` is rejected.

## Securing Spacebring webhooks

Spacebring's verifying page prints the Svix construction: the signed content is `{svix-id}.{svix-timestamp}.{raw body}`, the HMAC-SHA256 key is the base64-decoded secret after `whsec_`, and `svix-signature` is a space-delimited list of versioned signatures. It also stresses that the payload is the raw string body. A dependency-free version:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

Because the event name may not be in the body, this handler stores every verified delivery and routes on what it can see: `type` when present, otherwise the shape of the body:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

app.post('/webhooks/spacebring', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.SPACEBRING_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const body = parseJsonObject(req.body);
  if (!body) return res.sendStatus(400); // signed, but not a JSON object
  const message_id = req.headers['svix-id'] ?? req.headers['webhook-id'];
  try {
    await inbox.save(message_id, body); // keep everything until payloads are confirmed

    if (body.booking) {
      await calendar.syncBooking(message_id, body.type, body.booking);
    } else if (body.visit) {
      await hosts.notifyVisit(message_id, body.visit);
    } else if (body.order) {
      await shop.syncOrder(message_id, body.type, body.order);
    }
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

```

`inbox`, `calendar`, `hosts` and `shop` represent your own code. Once you've seen real deliveries, you can replace the shape checks with exact `type` values.

Svix's libraries reject timestamps older than five minutes, though Spacebring itself states no tolerance. Hookdeck sets none either, and its retries and replays reuse the original `svix-timestamp`, so a library check would fail on them behind Hookdeck. The function above checks the signature only.

> **Make Spacebring webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) records every Spacebring body exactly as sent, which is the quickest way to learn what an undocumented payload looks like.

## Spacebring webhook limitations and pain points

### Events are hard to identify

**The Problem:** Your handler can't reliably tell which event a body belongs to.

**Why It Happens:** The `type` value is never shown, `subscription.*` and `visitors.*` bodies have no `type` at all, and some events have no schema. The Svix headers don't help.

**Workarounds:**

* Route on the resource key (`booking`, `visit`, `order` and so on) and on `type` once you've confirmed its values.
* Subscribe to fewer events so that each body shape maps to fewer possibilities.

**How Hookdeck Can Help:** Hookdeck stores the full body of each delivery, and [filters](/docs/filters) can route on any field you discover, such as the presence of `booking`.

### No schemas for some events

**The Problem:** `location.*`, `resource.*` and `invoice.issued` arrive with fields you've never seen documented.

**Why It Happens:** The catalogue lists those events without a schema.

**Workarounds:**

* Validate defensively and log unknown shapes rather than failing.

**How Hookdeck Can Help:** Replay captured deliveries against your handler as you add support for each shape.

### Delivery policy is undocumented

**The Problem:** You don't know how long Spacebring keeps trying after a failure.

**Why It Happens:** Spacebring only says a message can be resent after a failure, with the same `svix-id`. It gives no schedule, timeout or disabling policy, and doesn't confirm Svix's defaults.

**Workarounds:**

* Acknowledge quickly and reconcile bookings and orders through the API after an outage.

**How Hookdeck Can Help:** Once Hookdeck has the event, its [retry](/docs/retries) policy governs delivery to your service.

### Owner-only configuration

**The Problem:** Developers can't add or change endpoints themselves.

**Why It Happens:** Only the network owner can register endpoints.

**Workarounds:**

* Ask the owner to register one stable URL and leave it in place.

**How Hookdeck Can Help:** With a Hookdeck source as that stable URL, developers can change where events go through [connections](/docs/connections) without involving the owner.

## Best practices

### Deduplicate on `svix-id`

A resent message keeps its `svix-id`. Record it with the change it caused; our [webhook idempotency guide](/webhooks/guides/implement-webhook-idempotency) explains how.

### Treat payment events as the trigger

For bookings and shop orders, act on `booking.paid` and `shop.order.paid` rather than the `created` events if access depends on payment.

### Return `200` for anything unrecognised

A non-`2xx` status makes Spacebring resend. Log unknown bodies and acknowledge them.

### Keep the secret server-side

The secret on the webhooks page is separate from API keys. Store it in your secret manager and never in client code.

## Conclusion

Spacebring's webhooks cover the whole workspace, from bookings to visitors, and arrive signed through Svix. The weak point is identifying events: capture real deliveries, route on what the bodies actually contain, and acknowledge everything you can't yet handle.

[Hookdeck Event Gateway](https://hookdeck.com) keeps a full record of those bodies and lets you change routing without asking the network owner. [Try Hookdeck free](https://dashboard.hookdeck.com/signup) with a Spacebring source.