How to set up webhooks in Clarion

A webhook makes Clarion send a signed POST to your endpoint when something happens — a milestone completes, a challenge is raised, metric values arrive. For an overview, see the webhooks integration page.

You need to be an owner or admin to manage webhooks.

Before you start

You need an endpoint that:

• is reachable at a public https:// URL (internal and private addresses are refused);
• accepts POST with a JSON body;
• answers with a 2xx status within 10 seconds, without redirecting.

A Zapier catch hook, an n8n Webhook node or a Make custom webhook all qualify. See Zapier and n8n.

Add a webhook

1. Go to Settings → Integrations and scroll to Webhooks. Check the badge beside the heading names the right company — webhooks belong to one company.
2. Paste your endpoint into the URL field.
3. Under Events, tick the events to receive:
   • Metric ingested — metric.ingested
   • Milestone completed — milestone.completed
   • Action item created — action_item.created
   • Action item completed — action_item.completed
   • Challenge created — challenge.created
   • Challenge resolved — challenge.resolved
4. Click Add Webhook.
5. Copy the signing secret from the green box (it starts whsec_). It’s shown once. Your endpoint uses it to verify signatures.
6. Click Done.

Send a test

Click Test next to the webhook. Clarion queues a webhook.test event to that endpoint, whichever events it’s subscribed to:

{
  "event": "webhook.test",
  "id": "clx...",
  "createdAt": "2026-10-07T09:12:44.120Z",
  "data": { "message": "Test event from Clarion" }
}

What each event sends

Every delivery has the same envelope — event, id (the delivery id), createdAt (when the event happened) and data:

data is deliberately small. To get the full record, call the read API with the id.

Headers on every request: X-Clarion-Event, X-Clarion-Delivery, X-Clarion-Timestamp, X-Clarion-Signature-V2, and the deprecated X-Clarion-Signature.

Check deliveries and retry

1. Under the webhook list, open Recent deliveries.
2. Each line shows the event, its status (success, failed or pending), the HTTP code your endpoint returned, the number of attempts, and when it was created.
3. Click Retry on a failed delivery to send it again. It keeps the original delivery id and createdAt, with a fresh signature.

Clarion retries automatically first: five attempts with exponential backoff starting at 5 seconds. Any non-2xx, a timeout or a redirect counts as a failure. Return 2xx quickly and do slow work afterwards.

Change or remove a webhook

Webhooks can’t be edited. To change the URL or events, add a new webhook, move your endpoint to its secret, then click Delete on the old one. Deleting stops all deliveries to it.