Webhooks
A webhook tells another system when something changes on a board. Each delivery is a signed JSON POST to an address you choose, and Studio retries it with a growing delay when it fails. Use one to start a pipeline when a slice becomes ready, to post to a chat, or to keep another tool in step with the board.
Add a webhook
Section titled “Add a webhook”You need to be a maintainer of the organization.
- Open Settings > Webhooks and select Add webhook.
- Enter a Name for your own reference.
- Enter the Address Studio should post to. It has to be an
httpsaddress on a public host. Addresses inside a private network, loopback addresses and plainhttpare refused. - Narrow what the webhook listens to, or leave everything on Any:
- Board: one board, or any board.
- Kinds of board: event model, brainstorming, concepts or design.
- What changed: the kinds of item, such as a slice or a comment.
- How it changed: added, renamed, removed, moved, updated, status changed, commented or restored.
- Select Save.
- Copy the Signing secret now. It is shown only once.
A webhook receives only changes that happen after you add it.
Each webhook’s Deliveries list shows what was sent and how it went: Delivered, Retrying or Given up, with the attempt and, for a retry, the time of the next one.
What a delivery looks like
Section titled “What a delivery looks like”Studio sends a POST with a JSON body and these headers:
| Header | Meaning |
|---|---|
Content-Type |
application/json; charset=utf-8 |
User-Agent |
Cratis-Studio-Webhooks/1 |
X-Studio-Signature |
The signature, described below |
X-Studio-Delivery |
The delivery’s id. The same id is sent on every retry of the same delivery |
X-Studio-Event |
The kind of change, such as slice.statusChanged |
X-Studio-Delivery-Attempt |
1 for the first try, 2 for the first retry, and so on |
The body:
{ "id": "5d3c0f64-8a7e-4b8e-9a1f-0c2e6d4b7a31", "kind": "slice.statusChanged", "organization": "Acme", "occurred": "2026-11-09T12:00:00.0000000+00:00", "sequenceNumber": 4182, "board": { "kind": "EventModel", "id": "9f1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d" }, "item": { "kind": "Slice", "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "name": "Place order" }, "action": "StatusChanged", "event": { "type": "…", "content": { } }}| Member | Meaning |
|---|---|
id |
The delivery’s id, the same as X-Studio-Delivery |
kind |
The item, then what happened to it, in camel case: slice.statusChanged, feature.added, comment.commented |
organization |
Your organization |
occurred |
When the change happened |
sequenceNumber |
The change’s position in your organization’s log of changes, which only grows |
board |
The board’s kind (EventModel, Brainstorming, Concepts or Design) and id |
item |
What changed: its kind, id and name |
action |
What happened: Added, Renamed, Removed, Moved, Updated, StatusChanged, Commented or Restored |
event |
The underlying change, with its type and content |
The item kinds are Board, ModuleCollection, Module, Feature, Slice, Command, Event, ReadModel, Actor, Specification, StickyNote, Comment, Chat and Region.
Treat event.content as informational and tolerate members you do not know. A retry sends exactly the same body as the first attempt.
Verify the signature
Section titled “Verify the signature”Every delivery carries a signature in the form:
X-Studio-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>The signature is an HMAC-SHA256, in lowercase hex, of the string <t>.<body>, computed with the webhook’s signing secret. <t> is the number in the header and <body> is the raw request body, exactly as received.
To verify a delivery:
- Read the raw body before parsing it. Re-serializing the JSON changes the bytes and breaks the check.
- Split the header on commas and read
tand everyv1. - Refuse the delivery when
tis more than five minutes from the time on your clock. This stops someone replaying a captured delivery later. - Compute the HMAC of
<t>.<body>with your secret and compare it with eachv1in constant time. Accept the delivery if one matches.
In Node.js:
import { createHmac, timingSafeEqual } from 'node:crypto';
export function isValid(secret, header, rawBody, toleranceSeconds = 300) { const parts = Object.fromEntries(header.split(',').map(p => p.trim().split('='))); const t = Number(parts.t); if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex'); const given = Buffer.from(parts.v1 ?? '', 'utf8'); const wanted = Buffer.from(expected, 'utf8'); return given.length === wanted.length && timingSafeEqual(given, wanted);}Respond, retries and duplicates
Section titled “Respond, retries and duplicates”Answer with any 2xx status within 10 seconds. Anything else counts as a failed attempt: a non-2xx status, no answer in time, or a connection that cannot be made. Studio keeps the start of your response, or the reason it got none, in the delivery list to help you debug.
A failed delivery is tried again after 1 minute, then 5 minutes, 30 minutes, 2 hours and 6 hours. After the sixth attempt it is Given up, and Studio does not retry it again.
Delivery is at least once. A delivery that was interrupted between sending and recording is sent again with the same X-Studio-Delivery id. Deduplicate on that id, and make your handler safe to run twice.
Deliveries are not guaranteed to arrive in order, especially when one is retried. Use sequenceNumber and occurred when order matters.
Rotate the secret
Section titled “Rotate the secret”Select Rotate secret next to a webhook. Studio signs deliveries with a new secret from then on, and shows it once. The receiver must be given the new secret, or its checks fail. A delivery that fails the signature check is simply retried, so rotate and update the receiver together.
Select Remove to delete a webhook. Nothing more is delivered to it.
Related
Section titled “Related”- Connect an AI agent over MCP reads and changes boards instead of reacting to them.
- Webhooks in your organization’s settings for the same page seen from the maintainer’s side.
- Your organization for roles and the rest of the settings.