# 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:

| Event | When |
|---|---|
| `task.awaitingAgent` | A task was set to wait on an agent. The visible task state that sets it is in design; until it ships, nothing emits this event. |

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.