API Keys & Webhooks [API keys: Starter+ read-only · Webhooks: Enterprise]
Purpose: programmatic access to your workspace data (API keys) and real-time event delivery to your own systems (webhooks).
Only Webhooks require the Enterprise tier. API Keys are available
starting on the Starter tier — every tier holds PUBLIC_API_READ
(read-only access; see the scopes below, all of which are *:read or
gate:read), and only Enterprise additionally holds PUBLIC_API (write
access). They are two separate Settings pages under the "Integrations"
category — API Keys and Webhooks each have their own card — rather than one
combined "API Keys & Webhooks" section.
API Keys
At Settings → API Keys, generate a key with a name and a set of granular scopes — this is not a binary "Read-only vs. Read-write" choice:
| Scope | Grants |
|---|---|
posture:read | Read posture scores and signals |
risks:read | Read risk register entries |
risks:write | Create and update risks |
compliance:read | Read frameworks and controls |
integrations:read | Read integration health |
gate:read | Evaluate the posture-as-code CI gate |
Copy the key immediately — it's shown once. Rotate by generating a new key, updating consumers, then revoking the old one from the same page.
Rate limits
Limits are per hour and scale with your subscription tier, not a flat 1,000 requests/minute:
| Tier | Requests per hour |
|---|---|
| Starter | 500 |
| Essentials | 2,000 |
| Command | 10,000 |
| Enterprise | 20,000 |
Requests over the limit get a 429. An operator override
(API_RATE_LIMIT) can raise this per deployment.
Webhooks
At Settings → Webhooks, register an HTTPS endpoint and subscribe to event types. The event catalog is not the risk/control/sync/user event list from the earlier version of this guide — it is:
| Event | Description |
|---|---|
posture.changed | Posture score updated |
risk.created | New risk registered |
risk.updated | Risk status changed |
compliance.milestone | Control status progressed |
integration.synced | Integration sync completed |
integration.failed | Integration sync failed |
alert.triggered | An Enterprise alert condition fired |
webhook.registration.circuit_opened | Another one of your webhooks stopped delivering |
Each payload is HMAC-SHA256-signed with your webhook secret; verify the
X-CMDash-Signature header on receipt (this part is unchanged).
Retry schedule
Corrected backoff — the earlier guide's 1 min / 5 min / 30 min / 2 hr / 8 hr schedule is wrong:
| Attempt | Delay |
|---|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 15 minutes |
| 4th retry | 1 hour |
| 5th retry | 24 hours |
After the 5th retry fails (6 total attempts, spanning just over 24 hours, not "within 24 hours"), the delivery is marked failed.
Circuit breaker
New since the last version of this guide: after enough consecutive terminal
failures, a registration's circuit "opens" and CMDash fires
webhook.registration.circuit_opened on your other webhooks so you learn
about the outage without having to watch delivery logs.
Related
- Integrations Management
- Notifications & Alerts — Slack/Teams/Email channels, a separate mechanism from webhooks.