Skip to content

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.

You need to be a maintainer of the organization.

  1. Open Settings > Webhooks and select Add webhook.
  2. Enter a Name for your own reference.
  3. Enter the Address Studio should post to. It has to be an https address on a public host. Addresses inside a private network, loopback addresses and plain http are refused.
  4. 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.
  5. Select Save.
  6. 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.

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.

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:

  1. Read the raw body before parsing it. Re-serializing the JSON changes the bytes and breaks the check.
  2. Split the header on commas and read t and every v1.
  3. Refuse the delivery when t is more than five minutes from the time on your clock. This stops someone replaying a captured delivery later.
  4. Compute the HMAC of <t>.<body> with your secret and compare it with each v1 in 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);
}

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.

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.