Preview. The endpoints on this page are illustrative and are likely to change as they move toward general availability. Documentation is published in advance so you can start shaping your integration; treat request and response details as subject to revision.

Setting up a webhook subscription

v1alpha1 webhook subscriptions are managed programmatically through the Platform API — no dashboard UI required. This page walks through creating your first subscription end-to-end.

Prerequisites

• A Platform API bearer token with the smart-scheduling:write scope. See Authentication for how to create one.
• A publicly reachable HTTPS endpoint that will receive events. Cirrus will not deliver to plain HTTP; localhost and RFC1918 private ranges are also rejected.

Create the subscription

Call POST /api/v1alpha1/webhook-subscriptions with your endpoint URL and the event types you want to receive:

The response returns the newly-created subscription — including the signingSecret, revealed exactly once:

Store the signingSecret in your secrets manager immediately. Cirrus does not retain a recoverable copy — if you lose it, delete the subscription and create a new one.

Full request/response schema and error codes are documented on the POST /api/v1alpha1/webhook-subscriptions endpoint page.

curl -s "https://altus.cirrusinsight.com/api/v1alpha1/webhook-subscriptions" \
  -H "X-Cirrus-Api-Key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endpointUrl": "https://example.com/cirrus-webhook",
    "events": [
      "scheduling.smartscheduler.scheduled",
      "scheduling.smartscheduler.rescheduled",
      "scheduling.smartscheduler.canceled"
    ],
    "description": "Production booking sync"
  }'

{
  "id": "sub_...",
  "endpointUrl": "https://example.com/cirrus-webhook",
  "events": [
    "scheduling.smartscheduler.scheduled",
    "scheduling.smartscheduler.rescheduled",
    "scheduling.smartscheduler.canceled"
  ],
  "status": "validating",
  "description": "Production booking sync",
  "createdAt": "2026-06-10T14:22:01Z",
  "payloadVersion": "v2",
  "signingSecret": "whsec_...",
  "signingSecretNote": "Save this now — it will not be shown again."
}

Endpoint validation

New subscriptions start in status: "validating". Cirrus sends a test delivery to your endpoint before flipping to active:

1. Your endpoint receives an event of type developer.webhook.test — a tiny envelope with an empty data field.
2. Verify the signature (see Security) and respond 2xx.
3. The subscription transitions to active. Real events begin flowing.

If your endpoint doesn't respond 2xx within the validation window, Cirrus retries the test event every few hours for 24 hours before disabling the subscription. You can watch delivery attempts in real time via:

GET /api/v1alpha1/webhook-subscriptions/{subscriptionId}/deliveries

What your endpoint receives

Every real delivery is a POST with:

• Body — a JSON Eventmodel envelope. The data field is a canonical Meetingmodel object for scheduling events.
• Headers:
  • Content-Type: application/json
  • X-Cirrus-Signature: sha256=<hex> — HMAC-SHA256 of the raw body signed with your signingSecret. Verify this before trusting the payload.
  • X-Cirrus-Event-Type — e.g., scheduling.smartscheduler.scheduled. Same value as body.eventType; header lets you route without JSON-parsing.
  • X-Cirrus-Correlation-Id — same value across every retry attempt for one event. Useful for log correlation.
  • X-Cirrus-Payload-Version: 2 — always 2 for v1alpha1 subscriptions. Lets a consumer that also serves v1 subscriptions branch on version without inspecting the payload.

Your endpoint should:

1. Verify the signature. See Security.
2. Check eventId against your idempotency store; if you've seen it, respond 200 immediately without reprocessing.
3. Handle the event.
4. Respond 2xx.

Anything other than 2xx — or no response within 30 seconds — is a failure and triggers retries.

Post-creation management

Every subscription operation lives on the Platform API:

Operation	Endpoint
List all subscriptions	GET /api/v1alpha1/webhook-subscriptions
Read one subscription	GET /api/v1alpha1/webhook-subscriptions/{id}
Delete a subscription	DELETE /api/v1alpha1/webhook-subscriptions/{id}
Inspect delivery history	GET /api/v1alpha1/webhook-subscriptions/{id}/deliveries

There is no PATCH — to change the endpoint URL, event list, or description, delete the subscription and create a new one. The signing secret is fresh on each new subscription; the old secret is invalidated when its subscription is deleted.