platform

Webhooks

CatState emits CloudEvents 1.0-compliant events for run lifecycles, spend updates, and catalog changes. Configure an endpoint and verify every delivery with an HMAC-SHA256 signature.

Event envelope

quantum.run.completedjson

{
  "specversion": "1.0",
  "id": "evt_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "type": "quantum.run.completed",
  "source": "https://api.catstate.dev/v1/runs",
  "subject": "runs/cs_run_8f9a2b1c4e5a",
  "time": "2026-08-31T14:30:28.450Z",
  "datacontenttype": "application/json",
  "data": {
    "run_id": "cs_run_8f9a2b1c4e5a",
    "status": "COMPLETED",
    "actual_cost_usd": 0.142,
    "duration_ms": 1420,
    "results": { "counts": { "00": 2041, "11": 2055 } }
  }
}

Event types

quantum.run.state_changed — QUEUED → RUNNING transitions and queue position updates.
quantum.run.completed — terminal state with results, cost, and duration.
finops.spend.updated — sub-key spend changes, powering live spend bars.
catalog.device.status_changed — device retirement, deprecation, and calibration alerts.

Verifying deliveries

Every POST carries an HMAC-SHA256 signature header computed over the raw body with your endpoint secret. Retries use exponential backoff (3 attempts); endpoints that persistently fail are moved to a dead letter queue.

verify.pypy

import hmac, hashlib
 
expected = hmac.new(
    WEBHOOK_SECRET.encode(),
    raw_body,                      # verify against the exact bytes received
    hashlib.sha256,
).hexdigest()
 
if not hmac.compare_digest(expected, signature_header):
    raise SecurityError("bad signature")

Real-time alternative

For dashboards and live views, subscribe to WebSocket topics instead (runs:{run_id}, org:{org_id}:spend) — same CloudEvents payloads, pushed instead of polled.