Webhooks

This page is for the developers who build your organization's own systems. A webhook tells your system at once when something changes in the workspace, for example when a project is created. On the Enterprise plan, an owner registers webhook endpoints (addresses on your own server) on the Enterprise page. Each event you subscribe to is sent to your endpoint as a signed JSON message, and sent again until your endpoint accepts it.

Adding an endpoint

Enterprise → Webhooks: enter an HTTPS URL and choose events, or Every event, which includes events added later. The signing secret (whsec_…) is shown once. Endpoints must be on public addresses; private, loopback and cloud-metadata addresses are refused, also when a public name resolves to one.

Events cover the workspace's own records: projects, issues, links, initiatives, milestones and outcomes, decisions, positions, publications, policies, votes and rituals. Fields that name a member are left out of the payload, and events about a restricted project or initiative are never sent.

The request

POST /your/endpoint
Content-Type: application/json
Webhook-Id: 7f1c…            (the event's ID: the same on every retry)
Webhook-Timestamp: 1792512000
Webhook-Event: project.created
Webhook-Signature: t=1792512000,v1=5c2e…

{"id":"7f1c…","type":"project.created","occurredAt":"…","organizationId":"…","aggregate":{"type":"project","id":"…"},"data":{…}}

Verifying the signature

v1 is the hex HMAC-SHA256, keyed with your secret, of <timestamp>.<raw body>. Compute it over the raw bytes you received, compare it in constant time with each v1 in the header (there are two during a rotation), and reject a timestamp more than five minutes from your clock. Treat Webhook-Id as an idempotency key: a delivery can arrive more than once.

Retries and failures

Any 2xx answer is success. Otherwise the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then abandoned. Answers are not followed through redirects and time out after 10 seconds. Twenty abandoned deliveries in a row disable the endpoint; re-activate it once it is fixed.

Deliveries lists each attempt's answer; Redeliver sends one again. Pause holds new deliveries until you resume. Send a test event posts a webhook.test event at once.

Rotating the secret

Rotate the secret shows a new secret once. For 24 hours deliveries are signed with both the new and the previous secret, so you can update your receiver without dropping any.