Skip to content
kumo

Studio API and webhooks

Your studio’s kumo server has a public API. A script, a CI job or a tool such as n8n, Zapier or Make can read and change the board, the wiki and the studio’s data. It can also ask to be told when something happens: a task is closed, someone comments, someone joins.

Every call runs as you. It reaches what you may reach and nothing more.

In kumo, open Settings, then API tokens, and make one.

  • Read tokens read and subscribe to events.
  • Write tokens can also change tasks, comments, milestones, fields and wiki pages.

The token is shown once. Keep it like a password. Revoking it stops every call made with it at once, and removes the webhooks made with it.

Terminal window
curl -X POST https://studio.example/hooks/api/v1/planner.task.move \
-H "Authorization: Bearer kumo_pat_..." \
-H "Content-Type: application/json" \
-d '{"id": "T-12", "status": "review"}'

The body is the method’s parameters as JSON. The answer is its result, or {"error": {"code", "message"}}.

GET https://studio.example/hooks/api/v1 lists every method with the schema of its parameters and of its answer.

StatusMeaning
401No valid token
403A read token tried to write
404The API has no such method
429More than 120 calls in a minute with one token

A tool gives you an address to post to. Subscribe it once:

Terminal window
curl -X POST https://studio.example/hooks/api/v1/webhooks.subscribe \
-H "Authorization: Bearer kumo_pat_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/...", "events": ["task.closed", "task.commented"], "project": "studio/game"}'
  • events names event ids, or a whole family with task.*. Leave it out to be told of every event.
  • project picks one project. Leave it out for every project you can see.

The answer holds the hook’s id and its secret. The secret is shown only here, so keep it.

From then on, kumo posts each event to the address:

POST /...
Content-Type: application/json
X-Kumo-Event: task.closed
X-Kumo-Delivery: dl-4f1c...
X-Kumo-Attempt: 1
X-Kumo-Signature: sha256=9e2a...
{"id": "dl-4f1c...", "event": "task.closed", "studio": "studio", "project": "studio/game",
"at": "2026-10-13T09:30:00+00:00", "subject": {"task": "T-12", "from": "review", "to": "done", ...}}

subject is what an automation on that event is given.

  • Answer quickly with any 2xx. Anything else, or no answer within 15 seconds, counts as a failure.
  • Failed posts are retried after 30 seconds, then 2 and 10 minutes, then 30 minutes and 1, 3, 6 and 12 hours: about a day in all. After that, kumo stops trying that event.
  • A post can arrive twice, for example when a server restarts while sending it. A retry carries the same X-Kumo-Delivery id and a higher X-Kumo-Attempt. Drop an id you have already handled.
  • Events can arrive out of order across retries. Use at in the body.
  • You are told only about projects you can still see.
  • webhooks.list shows each hook of a token, with its last delivery, its failures in a row and its last error.
  • webhooks.unsubscribe with {"id": "wh-..."} removes a hook.

kumo removes a hook by itself in three cases:

  • its address answers 410 Gone;
  • its last 100 tries all failed;
  • the token it was made with is revoked.

If an address stays down, at most 5,000 posts wait for it. Events after that are not kept for that hook until it catches up.

X-Kumo-Signature is sha256= followed by the HMAC-SHA256 of the raw body, keyed with the hook’s secret. Work it out the same way, and compare:

const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const genuine = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
EventWhen
task.createdA task is made
task.changedAnything but a task’s rank changes
task.movedA task goes to another column (from, to)
task.closedA task goes to a column that closes it
task.assignedSomeone is given a task (assignee)
task.commentedSomeone comments on a task (author, comment, text)
task.removedA task is deleted
milestone.changedA milestone is made, changed or deleted
review.requestedA version of a task’s work is added
review.verdictSomeone approves it or asks for changes
member.joined, member.leftSomeone joins or leaves a project or the studio

An automation can announce an event of its own (Announce an event, for example build.ready). Webhooks are told of it under that name.

  1. Add a Webhook node. Set its method to POST, then copy its Production URL. To check signatures, turn on the node’s Raw Body option.
  2. Subscribe that address with webhooks.subscribe, using the curl above or an HTTP Request node with your token in the Authorization header.
  3. Activate the workflow. Each event arrives as one execution, with the event in the body.
  4. To act back in kumo, add an HTTP Request node that posts to https://studio.example/hooks/api/v1/<method> with a write token.
  1. Make a Zap whose trigger is Webhooks by Zapier, event Catch Hook, and copy its address.
  2. Subscribe it with webhooks.subscribe.
  3. Close a task in kumo so that Zapier sees a sample, then build the rest of the Zap from its fields.
  4. To call kumo from a Zap, use Webhooks by Zapier, Custom Request, with method POST, your method’s address, and the header Authorization: Bearer kumo_pat_....
  1. Start a scenario with Webhooks, Custom webhook, add one, and copy its address.
  2. Subscribe it with webhooks.subscribe.
  3. Make an event happen in kumo so that Make learns the shape of the data, then add the modules that follow.
  4. To call kumo, use the HTTP, Make a request module with your token in the Authorization header.