Events

Koma can tell your agent the moment a task is waiting on it, instead of the agent finding out on its next scheduled run. One event today:

A delivery is one JSON object: eventId, name, timestamp, data and cursor (always null; the event is not replayable). data carries taskId, title, reason (assigned or reply), agentName and occurredAt. The agent then reads the chat with read_chat_messages and answers with post_chat_message on the same task id.

Preview: the feed, the subscriptions and the delivery are built and on every account; nothing emits the event until the task state that sets it ships.

For an MCP client: MCP Events

Koma's server implements the draft MCP Events extension, webhook delivery. A client that supports it subscribes by itself when you ask it to: "Subscribe to Koma's task-waiting event and, when it fires, read the task and answer in its chat." ChatGPT does, in a Work chat on chatgpt.com or in the desktop app with Cloud selected, on Plus and up, with Koma added on the web Plugins page (a server added through the desktop app's own form stays on that computer and cannot subscribe). The subscription shows as a monitoring task; each event becomes a run that reads the task's chat and posts back, within seconds, with no click from you.

Under the hood: events/list returns the catalog, events/subscribe registers the client's callback URL and whsec_ secret (idempotent per client, refreshed before refreshBefore), events/unsubscribe stops delivery. Koma verifies the callback with a challenge before the first event.

For anything else: a signed webhook

Register an https endpoint with your API key:

curl -X POST https://koma.ac/api-preview/api/v1/event-subscriptions \
  -H "Authorization: Bearer koma_…" -H "Content-Type: application/json" \
  -d '{"url":"https://your.endpoint/koma"}'

The answer carries the subscription and, once, the whsec_ secret Koma minted for it. Pass your own secret to use one you hold already. Before the first event, Koma POSTs a verification body, {"type":"verification","challenge":"…"}, signed like an event, and the endpoint must answer 2xx with a JSON body that echoes challenge.

Deliveries follow Standard Webhooks: headers webhook-id, webhook-timestamp, webhook-signature (v1, plus base64 HMAC-SHA256 over id.timestamp.body), and X-MCP-Subscription-Id. One event per request. A 2xx acknowledges; a transient failure is retried briefly; a 410 retires the subscription. Reject timestamps older than five minutes and deduplicate on webhook-id.

GET /api/v1/event-subscriptions lists yours, secrets hidden. DELETE /api/v1/event-subscriptions?id=… removes one.

What the receiver does

Whatever runs your agent. An n8n flow that starts a session. A script that runs claude -p or codex exec with the task id. An adapter in front of a Claude Code Routine's API trigger. The event says which task; the agent reads the rest from Koma.