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.

Introduction to Webhooks (v2)

Webhooks push events from Cirrus Insight to an HTTPS endpoint you control. When something happens in the platform — a meeting is booked, rescheduled, canceled — Cirrus sends a signed HTTP POST to your endpoint with a JSON payload describing the change. You don't poll for data; you receive it as it happens.

The webhooks documented under v1alpha1 deliver the v2 payload version — a canonical Eventmodel envelope wrapping the Platform API's Meetingmodel shape. Partners integrating against both the Platform API and webhooks use one Meeting mapper across both surfaces.

Two payload versions coexist

• v2 (this documentation) — new canonical shape. Delivered on subscriptions created via POST /api/v1alpha1/webhook-subscriptions, and on subscriptions that explicitly opt into v2. Recommended for new integrations.
• v1 (v0.1 documentation) — legacy shape with nested meetingInfo. Delivered on subscriptions created via the pre-v1alpha1 developer dashboard. Continues to work indefinitely; no forced migration.

Your subscription's payloadVersion is set once at creation and is immutable. To move an existing integration to v2, create a new subscription — the old one keeps working.

Concepts

• Subscription. A durable configuration in Cirrus Insight that says "when event X happens in my org, POST it to URL Y." Managed via the Platform API's /api/v1alpha1/webhook-subscriptions endpoints.
• Delivery. A single HTTP POST to your endpoint. One event may produce multiple deliveries if the first attempts fail — retried automatically with exponential backoff.
• Signing secret. A 32+ char shared secret (whsec_... prefix), revealed once at subscription creation. Your endpoint uses it to verify that each delivery genuinely came from Cirrus Insight and wasn't tampered with in transit. See Security.
• Event catalog. The set of eventType strings a subscription can subscribe to. See Event Types.

End-to-end flow

1. Create a subscription — POST /api/v1alpha1/webhook-subscriptions with your endpoint URL and the event types you care about. The response returns the signingSecret exactly once. Store it in your secrets manager immediately.
2. Endpoint enters validating state — Cirrus sends a test delivery. Your endpoint responds 2xx; subscription moves to active.
3. Cirrus emits an event — say, a meeting is booked. Cirrus builds an Eventmodel envelope with the canonical Meetingmodel shape in data.
4. Cirrus POSTs to your endpoint — with Content-Type: application/json, a signed body, and identifying headers (see Security and Lifecycle).
5. Your endpoint responds 2xx — usually within a few seconds. Cirrus considers the delivery successful.
6. Any non-2xx response or timeout triggers retries — up to 3 times with exponential backoff over a 24-hour window.

Benefits

• Real-time. No polling; events fire when they happen.
• Reliable. Retries with exponential backoff; failed deliveries are queryable via the delivery-log endpoint.
• Idempotent. Every delivery carries a stable eventId; retries share the same id. Deduplicate on your side to survive network hiccups without processing the same event twice.
• Signed. HMAC-SHA256 on the raw body ensures the payload is authentic and unmodified.
• Canonical shape. The same Meeting object you get from the Platform API is the one delivered in event.data. One mapper, two surfaces.

Next steps

1. Set up your first subscription
2. Understand the signature verification recipe
3. Learn the delivery lifecycle and retry policy
4. Browse the event catalog
5. Review the Event and Meeting model shapes