Webhooks

​

Quickstart

1. Baseline. Pull the club grid once to render the calendar and store the returned cursor: GET /v1/platform/availability?clubId=8&from=…&to=….
2. Register an HTTPS endpoint (below) and store the whsec_… signing secret.
3. Receive & verify. On each POST, check the 1Club-Signature header against the raw body (verify the signature) and respond 2xx within 10 seconds.
4. Re-pull. Fetch the affected window named in the event’s data and update those slots: GET /v1/platform/areas/{areaId}/availability?from=…&to=…. Keep the highest version/sequence you’ve applied.
5. Reconcile. On a slow timer — and after any downtime — call GET /v1/platform/availability/changes?since=<cursor>, apply the deltas, and store the new cursor.

​

Register an endpoint

​

The availability.changed event

{
  "id": "evt_9f2c4a1b8d7e4c2fa0b1c2d3e4f5a6b7",
  "type": "availability.changed",
  "occurredAt": "2026-07-20T16:32:04.115Z",
  "sequence": "48213",
  "organizationId": 8,
  "data": {
    "clubId": 8,
    "areaId": 51,
    "window": { "from": "2026-07-20T17:00:00.000Z", "to": "2026-07-20T18:00:00.000Z" },
    "reason": "booking.created"
  }
}

• id - unique per event. Deduplicate on it (delivery is at-least-once).
• sequence - the change’s position in your org’s change feed. Compare it to the version on an availability read to know whether your last read already reflects this change; use it as the since cursor for the change feed.
• data.reason - a coarse cause label, e.g. booking.created, booking.cancelled, booking.updated, booking.released, class.reserved, class.reservation_removed, event.published, event.unpublished, event.cancelled, event.updated, area.updated. Treat it as a hint; always re-pull for truth.

​

sequence, version, and cursor

​

Verify the signature

import crypto from "node:crypto";

function verify(rawBody: string, header: string, secret: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(header.split(",").map(kv => kv.split("=")));
  const t = Number.parseInt(parts.t, 10);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(parts.v1, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

​

Delivery, retries, and idempotency

• Respond within 10 seconds. Any 2xx marks the delivery successful. A non-2xx, a connection error, or a response slower than the 10-second timeout counts as a failure. Do the minimum synchronously (verify, enqueue, ack) and re-pull availability asynchronously.
• At-least-once. You may receive the same id more than once. Deduplicate on id and make handling idempotent (re-pulling availability already is).
• Retries with backoff. A failed delivery is retried up to 7 attempts total — the first immediately, then after roughly 1m, 5m, 30m, 2h, 6h, and 24h (about 33 hours end to end). Timing has a few seconds of jitter.
• Auto-disable. After the 7th attempt fails, the endpoint is disabled automatically and the reason is shown under Settings → APIs and MCP. Re-enable it (and rotate the secret if needed) once healthy, then reconcile with the change feed to catch up on everything sent while it was down.
• Ordering is not guaranteed. Use sequence if you need to order or detect gaps; because events are invalidations you re-pull for, exact order rarely matters.

​

Reconcile after downtime

​

Troubleshooting

• Deliveries stopped arriving. The endpoint was likely auto-disabled after repeated failures — check Settings → APIs and MCP for the disable reason, fix your endpoint, re-enable it, then reconcile from your last cursor.
• Signature always fails. You’re almost certainly hashing a re-serialized body — verify against the exact bytes received (see the note above), and confirm you’re using the current secret (rotating it invalidates the old one immediately).
• Correlate and dedupe on your side. Log the 1Club-Event-Id and 1Club-Delivery-Attempt headers: the event id lets you dedupe, and the attempt number tells first deliveries apart from retries.