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.
Make a token
Section titled “Make a token”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.
Call a method
Section titled “Call a method”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.
| Status | Meaning |
|---|---|
| 401 | No valid token |
| 403 | A read token tried to write |
| 404 | The API has no such method |
| 429 | More than 120 calls in a minute with one token |
Webhooks: be told when something happens
Section titled “Webhooks: be told when something happens”A tool gives you an address to post to. Subscribe it once:
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"}'eventsnames event ids, or a whole family withtask.*. Leave it out to be told of every event.projectpicks 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/jsonX-Kumo-Event: task.closedX-Kumo-Delivery: dl-4f1c...X-Kumo-Attempt: 1X-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.
Delivery
Section titled “Delivery”- 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-Deliveryid and a higherX-Kumo-Attempt. Drop an id you have already handled. - Events can arrive out of order across retries. Use
atin the body. - You are told only about projects you can still see.
webhooks.listshows each hook of a token, with its last delivery, its failures in a row and its last error.webhooks.unsubscribewith{"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.
Check that a post is your studio’s
Section titled “Check that a post is your studio’s”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));Events
Section titled “Events”| Event | When |
|---|---|
task.created | A task is made |
task.changed | Anything but a task’s rank changes |
task.moved | A task goes to another column (from, to) |
task.closed | A task goes to a column that closes it |
task.assigned | Someone is given a task (assignee) |
task.commented | Someone comments on a task (author, comment, text) |
task.removed | A task is deleted |
milestone.changed | A milestone is made, changed or deleted |
review.requested | A version of a task’s work is added |
review.verdict | Someone approves it or asks for changes |
member.joined, member.left | Someone 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.
- 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.
- Subscribe that address with
webhooks.subscribe, using the curl above or an HTTP Request node with your token in theAuthorizationheader. - Activate the workflow. Each event arrives as one execution, with the event in the body.
- To act back in kumo, add an HTTP Request node that posts to
https://studio.example/hooks/api/v1/<method>with a write token.
Zapier
Section titled “Zapier”- Make a Zap whose trigger is Webhooks by Zapier, event Catch Hook, and copy its address.
- Subscribe it with
webhooks.subscribe. - Close a task in kumo so that Zapier sees a sample, then build the rest of the Zap from its fields.
- 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_....
- Start a scenario with Webhooks, Custom webhook, add one, and copy its address.
- Subscribe it with
webhooks.subscribe. - Make an event happen in kumo so that Make learns the shape of the data, then add the modules that follow.
- To call kumo, use the HTTP, Make a request module with your token in
the
Authorizationheader.