Polling an API to find out whether something changed is slow and wasteful. Webhooks turn it around: when something happens in Clarion, Clarion sends a POST to your endpoint straight away. Use them to post a finished milestone to chat, open a task in another tool when an action item is created, or refresh a dashboard when new metric values land.
Events
| Event | Fires when |
|---|---|
milestone.completed | A milestone’s status changes to completed |
action_item.created | An action item is created |
action_item.completed | An action item is completed |
challenge.created | A challenge is raised |
challenge.resolved | A challenge is resolved |
metric.ingested | Values arrive through the ingest API, a push URL or a scheduled fetch |
webhook.test | You press Test on a subscription (not subscribable) |
Each subscription picks the events it wants, and you can have several subscriptions pointing at different endpoints.
What arrives
{
"event": "milestone.completed",
"id": "clx...",
"createdAt": "2026-08-27T11:04:12.331Z",
"data": {
"id": "clm...",
"title": "Launch the partner programme",
"companyId": "clc...",
"completedAt": "2026-08-27T11:04:12.298Z"
}
}The top-level id is the delivery id; data describes the thing that changed. Headers name the event (X-Clarion-Event), the delivery (X-Clarion-Delivery) and carry the signature.
Signed, so you can trust it
Each subscription has its own signing secret, shown once when you create it. Every request carries:
X-Clarion-Signature-V2: t=1759823052,v1=5f2b...v1 is an HMAC-SHA256, using your secret, of the timestamp, a full stop and the raw request body. Because the timestamp is signed, you can reject anything older than a few minutes, which stops a captured request from being replayed later. Verify webhook signatures has working code.
An older X-Clarion-Signature header, signed over the body alone, is still sent for existing integrations. It’s deprecated — verify the V2 header instead.
Delivery you can rely on
- Retries. Any non-2xx answer, a timeout after 10 seconds or a redirect counts as a failure. Clarion tries five times with exponential backoff starting at 5 seconds.
- Idempotency. Retries reuse the same
X-Clarion-Deliveryid, so storing the ids you’ve handled makes processing safe to repeat. - A log. Settings → Integrations → Webhooks → Recent deliveries lists recent attempts with status, response code and attempt count. A Retry button redelivers a failed one with the original id and a fresh signature.
- Safe targets. Endpoints must be
https://on public addresses. Redirects are never followed.
Set-up
Owners and admins add webhooks under Settings → Integrations → Webhooks: paste the endpoint URL, tick events, and press Add Webhook. Then press Test to send a webhook.test event. Full steps are in Set up webhooks, and React to changes with webhooks covers designing a receiver that holds up in production.
No-code tools work too: a Zapier catch hook, an n8n Webhook node or a Make custom webhook can all be the endpoint. See Zapier and n8n.