Webhooks | Trace.Space Help Center

Webhooks push a signed JSON message to a URL you own whenever something you subscribed to happens. There is no page for them in the app; org admins manage subscriptions through the core API under /core/webhooks.

Call	What it does
`GET /core/webhooks/eventTypes`	Lists the event types you can subscribe to.
`GET /core/webhooks/eventTypes/payloads`	Returns one sample payload per event type, so you can see the JSON shape before subscribing.
`POST /core/webhooks`	Creates a subscription from a `name`, an HTTPS `url` and a list of `eventTypes`. The response includes the signing `secret`, shown only this once. You can supply your own secret of 16 to 1024 characters instead.
`GET /core/webhooks`, `GET /core/webhooks/{id}`	Lists subscriptions, with delivery statistics: last delivery, last failure and its reason, consecutive failures, totals.
`PUT /core/webhooks/{id}`	Changes the name, URL, event types or `isActive`.
`DELETE /core/webhooks/{id}`, `PUT /core/webhooks/{id}/restore`	Deactivates a subscription, and brings it back.
`PUT /core/webhooks/{id}/rotateSecret`	Issues a new secret, yours or a generated one. Returned once.
`POST /core/webhooks/{id}/test`	Sends a `webhook.ping` event through the normal delivery path.

Event types cover items (item.created, item.updated, item.deleted, item.restored, item.field_deleted, item.field_renamed, item.version_reverted), traces (trace.created, trace.updated, and target and source changes), comments (comment.created, comment.updated, comment.deleted) and reviews (review.created, review.updated, review.closed, items and participants added or removed).

Verifying a delivery. Every POST carries these headers: X-TraceSpace-Event, X-TraceSpace-Delivery (a stable ID you can use to ignore duplicates), X-TraceSpace-Timestamp, X-TraceSpace-Signature, X-TraceSpace-Attempt and X-TraceSpace-Sequence. The signature is sha256= followed by an HMAC-SHA256, computed with your secret over the string <timestamp>.<body>. Recompute it and compare before trusting the payload, and reject old timestamps to block replays.

Retries. Respond with a 2xx within a few seconds. A timeout, a 5xx, a 408 or a 429 is retried up to 5 times in total, with delays of 1, 4, 16 and 64 seconds. Any other 4xx is final. Deliveries are not guaranteed to arrive in order, so use the sequence header if order matters.

Webhooks need a bearer token like any other API call; see API and automation overview for how to get one and which headers to send.