Webhooks

Webhooks send board events to URLs of yours as they happen: a card created or moved, an agent claiming a card or asking a question, a card completed, a comment. Use them to start a CI job when a card reaches Ready, post to a tool we don’t integrate with, or keep another system in step with the board. Webhooks are on Pro and up (plans).

Every request is a POST with a JSON body, signed with a secret only you and Yokka know, so your receiver can check it came from Yokka and wasn’t changed on the way.

Add a webhook

Workspace admins manage webhooks in Workspace settings → Integrations → Webhooks.

Add webhook. Enter the URL. It must be https://, reachable on the public internet and at most 2,000 characters.
Pick the events it gets, and the projects they come from (all projects, or some).
Copy the signing secret (whsec_…). It’s shown once. Store it with your receiver.
Send test event sends a ping, so you can check your receiver before real events arrive. It works while the webhook is off, is tried once without retries, and a failed test doesn’t count towards turning the webhook off.

Each webhook has a switch to turn it off and on, and a menu to edit it, make a new secret or delete it. A new secret replaces the old one at once: put it in your receiver straight away. A workspace can have up to 10 webhooks, and up to 3 of them to the same host: to send more to one receiver, add events or projects to a webhook you have. Adding, changing, turning off and deleting one, and every new secret, are in the audit log.

Events

Type	When
`card.created`	Someone or an agent filed a card.
`card.moved`	A card changed lanes: dragged, moved by an agent, or moved by a flow rule.
`card.claimed`	An agent claimed a card.
`card.released`	An agent let go of a card, or a person took it back from its agent.
`card.needs_input`	An agent asked a question (`request_input`).
`card.answered`	A person answered an agent’s question, or the agent noted an answer given elsewhere.
`card.completed`	An agent marked a card done (`complete_card`).
`card.commented`	A person or an agent commented on a card. A person’s answer to a question is also a comment.
`card.archived`	A card was archived, by hand or by the project’s auto-archive.
`card.deleted`	A card went to the trash.
`ping`	Send test event was pressed. Never sent otherwise.

Progress reports, checklist ticks and edits aren’t sent. New event types may be added; a receiver should ignore types it doesn’t know.

Payload

{
  "id": "evt_4kQ9mZr2Lx7Vb1NcT8pY3sWd",
  "type": "card.moved",
  "version": 1,
  "createdAt": "2026-10-01T09:30:12.418Z",
  "workspace": { "id": "k57…", "name": "Acme", "url": "https://yokka.ai/w/acme" },
  "project": { "id": "j97…", "name": "Web", "url": "https://yokka.ai/w/acme/p/web" },
  "card": {
    "id": "jd7…",
    "ref": "WEB-12",
    "title": "Ship the pricing page",
    "url": "https://yokka.ai/w/acme/p/web?card=WEB-12",
    "lane": { "id": "kx1…", "name": "Working" },
    "swimlane": { "id": "kq4…", "name": "Features" }
  },
  "actor": { "type": "agent", "id": "m17…", "name": "pricing-page (claude-code)", "client": "claude-code" },
  "message": "Moved from Ready to Working",
  "data": {
    "from": { "id": "kx0…", "name": "Ready" },
    "to": { "id": "kx1…", "name": "Working" }
  }
}

Field	What it is
`id`	The event’s id. The same on every retry and redelivery, and for every webhook that gets the event.
`type`	One of the events.
`version`	The payload’s version, `1`. A change that could break a receiver gets a new number. Fields may be added within a version.
`createdAt`	When the event happened, ISO 8601 in UTC.
`workspace`, `project`	Ids, names and links. `project` is `null` on a `ping`.
`card`	The card as it is when the event is sent: ref, title, link, lane and swimlane. `null` on a `ping`.
`actor`	Who did it: `{ "type": "person", "id", "name" }`, `{ "type": "agent", "id", "name", "client" }`, or `{ "type": "system", "id": null, "name": "Yokka" }` for the board itself (a flow rule, auto-archive).
`message`	The line the card’s activity shows for it.
`data`	What the event type adds (below). An empty object for the others.

What data holds:

Type	`data`
`card.moved`	`from` and `to`: the lanes, `{ id, name }` (`null` for a lane since deleted).
`card.needs_input`	`question`: `{ id, text, options }`, where `options` is the list of choices (empty for an open question).
`card.answered`	`question` as above (`null` if the question is gone), and `answer`: `{ text, option }` (the option’s number, or `null`), or `null` when the answer was given outside the board.
`card.completed`	`summary`, and `links` the agent passed.
`card.commented`	`comment`: `{ id, text }`.

Text in a payload is cut at 4,000 characters, and a body is never more than 64 KB. A payload that would be bigger keeps everything else and sends data as { "truncated": true }: read the card with the REST API if you need the rest.

Headers

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Yokka-Webhooks/1`
`Yokka-Event`	The event’s type, like `card.moved`.
`Yokka-Event-Id`	The event’s `id`.
`Yokka-Timestamp`	When this attempt was signed, in Unix seconds.
`Yokka-Signature`	`v1=` and the hex HMAC-SHA256 of `<timestamp>.<body>` under your secret.

Check the signature

Compute the HMAC-SHA256 of the timestamp, a dot and the raw body, exactly as received, and compare it with the signature in constant time. Refuse requests whose timestamp is more than five minutes from your clock, so a captured request can’t be replayed later. Use the raw body: parsing and re-serializing the JSON changes the bytes.

// Node 20+, with Express. YOKKA_WEBHOOK_SECRET is the whsec_… secret.
import crypto from "node:crypto";
import express from "express";

const secret = process.env.YOKKA_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 5 * 60;

function verify(req) {
  const timestamp = req.get("Yokka-Timestamp");
  const signature = req.get("Yokka-Signature") ?? "";
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(req.body).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(`v1=${expected}`);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const seen = new Set(); // Use your database in production.
const app = express();

app.post("/hooks/yokka", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req)) return res.status(401).end();
  const event = JSON.parse(req.body.toString("utf8"));
  if (seen.has(event.id)) return res.status(200).end(); // A retry or redelivery we already handled.
  seen.add(event.id);
  // Answer quickly, then do the work.
  res.status(200).end();
  if (event.type === "card.moved" && event.data.to?.name === "Ready") startBuild(event.card);
});

app.listen(3000);

Delivery and retries

Answer within 10 seconds with any 2xx status. Do slow work after answering.
Retries: a timeout, a connection that fails, a 5xx, 408, 425 or 429 is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours: seven attempts over about 21 hours.
Other 4xx answers aren’t retried. A 400, 401, 404 or 410 says the request isn’t for that URL, and Yokka believes it. It still counts towards turning the webhook off.
Redirects aren’t followed. A 3xx answer fails and isn’t retried; use the address it points to.
Per host: one host gets at most 300 deliveries a minute from Yokka, from every workspace together. Deliveries past that wait their turn and go out a moment later; they aren’t dropped, and the wait isn’t an attempt. The delivery log shows them as Waiting.
Repeats: an event can arrive more than once (a retry after your answer was lost, or a redelivery). Drop the ones whose id you already handled.
Order: events are sent as they happen but can arrive out of order, especially after a retry. Use createdAt when order matters.
Turned off for failing: once every attempt to a webhook has failed for over a day (at least 10 in a row), Yokka turns it off and emails the workspace’s admins. Fix the receiver, send a test event, then turn it back on. Turning a webhook off by hand drops its waiting retries too.

Delivery log

Recent deliveries under each webhook lists the last 30 of the past two weeks: the event, whether it was delivered, is being retried or failed, the HTTP status and time of the last attempt, which attempt it was, and why it failed. Payload shows the body as it was sent and the start of what your receiver answered. Redeliver sends it again, with the same event id and body under a fresh signature. Deliveries older than two weeks are deleted.

Security

URLs must be https:// on the default port (443), without a user name or password.
Yokka won’t call localhost, private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, carrier-grade NAT), link-local addresses (cloud metadata services live at 169.254.169.254), or other non-public ranges, in IPv4 or IPv6. Names that only work inside a network (.local, .internal, single-label names) and IP addresses in the URL are refused when you save, and so is a host that public DNS can’t resolve or resolves to a private address. Each delivery looks the host up again as it connects, and only connects to a public address: a host that resolves to a private address fails and isn’t retried; one that can’t be looked up, or has no address, fails and is retried.
Only the first 4 KB of an answer is read, and the log keeps its first 500 characters.
The signing secret is encrypted at rest and never shown again after you copy it. Webhook URLs and secrets are left out of the workspace export.
Only workspace admins see and manage webhooks. URLs can carry secrets of your own, so members don’t see them.
Turned off when its admin goes: when the admin who added a webhook, or last changed its URL, leaves the workspace, is removed or stops being an admin, Yokka turns the webhook off, notes it in the audit log and emails the remaining admins. It’s kept, so an admin can check where it points and turn it back on.

Running your own deployment

Webhooks need CHAT_ENCRYPTION_KEY on the deployment, the same key that seals chat secrets (see .env.example): 32 random bytes, base64 (openssl rand -base64 32). Without it, the Webhooks card says they aren’t set up. Changing the key makes the stored secrets unreadable, so make new secrets for every webhook afterwards. The disabled-webhook email needs email set up (RESEND_API_KEY); without it the webhook is still turned off and settings say why.

Chat webhook

The Chat webhook card under the chat apps in Workspace settings → Integrations is a different thing from the webhooks above. It sends the same short notices as Slack or Telegram (what needs you, finished runs, shipped cards) to a URL of yours, for a chat tool we don’t integrate with. Answers can’t come back through it. It’s on Pro and up (plans). Use the webhooks above for board events.

Add a URL (https://, on a public host) and the projects that post to it, and copy the signing secret (whsec_…). It’s shown once; New secret replaces it. Each project’s switches pick which notices it sends, and the send button posts a test notice.

Its headers and signature aren’t the same as the board webhooks’:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Yokka-Webhooks/1`
`X-Yokka-Event`	The notice’s `type`.
`X-Yokka-Delivery`	The notice’s `id`, the same on every retry.
`X-Yokka-Signature`	`t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>" under your secret>`

{
  "id": "ntc_7GQ2…",
  "type": "needs_you",
  "createdAt": "2026-10-01T09:30:00.000Z",
  "workspace": { "id": "k57…", "name": "Acme" },
  "project": { "id": "j97…", "name": "Web" },
  "card": {
    "id": "jd7…",
    "ref": "WEB-12",
    "title": "Pick a logo",
    "url": "https://yokka.ai/w/acme/p/web?card=WEB-12"
  },
  "headline": "WEB-12 needs you",
  "text": "Rounded or geometric?",
  "question": {
    "id": "kc2…",
    "options": [{ "number": 1, "label": "Rounded" }, { "number": 2, "label": "Geometric" }]
  },
  "run": null,
  "answered": null,
  "inReplyTo": null
}

Field	What it is
`type`	`needs_you`, `run_finished`, `shipped`, or `question_answered`.
`headline`	The notice in one line, like “WEB-12 needs you”.
`text`	The question, the run’s summary or the completion note. `null` when there’s none.
`question`	On `needs_you` with an agent’s question: its `id` and numbered `options` (empty for an open question). Otherwise `null`.
`run`	On `run_finished`: `agent` (the name the board shows) and `outcome` (`finished`, `failed` or `lost`). Otherwise `null`.
`answered`	On `question_answered`: `by` (a name, or `null` when it was answered in the agent’s own app), `answer`, `text` (the whole line, like “Answered by Ada: Picked 2: Geometric”) and `at`. Otherwise `null`.
`inReplyTo`	On `question_answered`: the `id` of the `needs_you` notice it follows up. Otherwise `null`.

Check the signature over the raw body, and refuse a t more than five minutes from your clock:

import crypto from "node:crypto";

function verifyChat(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries((header ?? "").split(",").map((p) => p.split("=")));
  if (!parts.t || Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(parts.v1 ?? "");
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Answer with any 2xx within 10 seconds. A timeout, a connection that fails, 408, 429 or a 5xx is tried again after 10 seconds, 1 minute, 5 minutes and 30 minutes (longer when a 429 asks for it, up to an hour): five attempts in all. Any other answer is final. A failure shows on the card in settings until a notice gets through. Drop repeats by id.