# Watchers

> Run code for every matching event, in order, with retries.

Source: https://docs.workbus.dev/guides/watchers/
Markdown: https://docs.workbus.dev/guides/watchers/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

A watcher is a tail expression and somewhere to deliver what matches it. The board hands each matching event to your code once, one at a time per thread and in the thread’s order, and retries what fails. Your code can be as slow as it likes: delivery runs off the write path, so it never holds the board.

src/worker.ts

```ts
import { WorkerEntrypoint } from 'cloudflare:workers'
import { defineWorkbus } from 'workbus'
import type { GatewayEnv } from 'workbus/gateway/gateway.ts'


export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus(() => ({
  watch: {
    // Every event under deploys/, delivered in order per thread to this Worker's Ops entrypoint.
    ops: { tail: 'deploys/', sink: { kind: 'service', binding: 'OPS', method: 'onEvent' } },
  },
}))


type BoardEvent = { cursor: string; type: string; message?: { id: string; re: string | null; text: string } }
type Delivery = { attempt: number; match: string; watcher: string; name: string; board: { reply(id: string, input: string): Promise<unknown> } }


export class Ops extends WorkerEntrypoint<GatewayEnv> {
  async onEvent(event: BoardEvent, context: Delivery): Promise<void> {
    const message = event.message
    // Answer each new thread under deploys/ once; the watcher's own replies come back as events too.
    if (event.type !== 'message.posted' || !message || message.re !== null) return
    await context.board.reply(message.id, 'seen by the ops watcher (try ' + context.attempt + ')')
  }
}


export default { fetch: (request: Request, env: GatewayEnv) => gateway(request, env) }
```

This is the Worker of a deployment that depends on `workbus` ([Deploy and operate](/guides/deploy-and-operate/#a-deployment-of-your-own) sets one up). The `OPS` binding is the Worker’s own `Ops` entrypoint, in its `wrangler.jsonc`:

wrangler.jsonc

```jsonc
"services": [{ "binding": "OPS", "service": "workbus", "entrypoint": "Ops" }]
```

A post under `deploys/`, and the watcher’s answer in its thread:

```plaintext
$ wb post deploys/web 'v7 is live'
posted #23 in deploys/web
$ wb read 23
#23  jared  2026-11-20 15:33
  v7 is live


#24  ops  2026-11-20 15:33
  seen by the ops watcher (try 1)
```

## Config watchers

A deployment’s own watchers are in its `defineWorkbus` config, under `watch`, by ID. Each has a `tail` and a `sink`, and runs on every board the deployment serves. A watcher sees what lands after it’s deployed: a new watcher on a board in use starts at the head, and gets nothing from before.

| Sink                                    | Delivers                                                                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ kind: 'service', binding, method? }` | calls `env[binding][method](event, context)`, a Worker entrypoint over RPC; `method` is `onEvent` unless you name another                                     |
| `{ kind: 'url', url, secret? }`         | POSTs `{ event, board, watcher, match, attempt }` as JSON, with `x-board-match`, and `x-board-signature: sha256=<hex HMAC of the body>` when there’s a secret |

A service sink’s `context` holds `watcher`, `match` (the delivery’s ID, the same on every try), `attempt`, `name` (the board’s name), and `board`: the board, acting as the watcher. It has `me`, `message`, `threads`, `post`, `reply`, `react`, `label`, and `typing`, and what it writes is by `workbus:watch:<id>`. Its writes are events like any other, so a watcher whose tail matches its own channel skips its own messages.

A delivery fails when the sink throws (or a URL answers anything but 2xx). Here a URL sink refused the first two tries of one alert:

```plaintext
23:32:24 hooks attempt 1 message.posted "disk at 91% on db-2" signed true -> 200
23:32:24 hooks attempt 1 message.posted "flaky probe on edge-7" signed true -> 503
23:32:25 hooks attempt 2 message.posted "flaky probe on edge-7" signed true -> 503
23:32:27 hooks attempt 3 message.posted "flaky probe on edge-7" signed true -> 200
```

That watcher was `hooks: { tail: 'alerts', sink: { kind: 'url', url: 'https://hooks.example.com/board', secret: env.HOOK_SECRET } }`, and the receiver checked each signature.

## Order and retries

Each watcher has a Mailbox, a Durable Object that delivers its matches:

* **One at a time per thread, in order.** A thread’s next match waits until the one before it is delivered or given up. Threads go in parallel, up to 16 at once.
* **Retries with backoff.** A failed try is tried again after 1 second, doubling up to 30 seconds. Each try holds a 5-minute lease, so a try that never ends is tried again.
* **Five tries.** After the fifth, the match is recorded as failed and its thread goes on.
* **At least once.** A match is delivered until a try succeeds, so a sink that has side effects keys them by `context.match`.

The Ledger hands matches to the Mailbox after each write commits, from a cursor it keeps, so a write never waits for a watcher and a watcher never misses a write.

## Registered watchers

A program that isn’t part of the deployment registers watchers on a board and pulls their matches. Registering again replaces the registration: one per principal, up to 64 watchers.

pull-watcher.mjs

```js
// A watcher that runs anywhere: register a tail, then pull matches, handle each, and ack it.
const url = process.env.WORKBUS_URL
const headers = { authorization: 'Bearer ' + process.env.WORKBUS_TOKEN, 'content-type': 'application/json' }
const call = async (method, path, body) => {
  const response = await fetch(url + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body) })
  if (!response.ok) throw new Error(method + ' ' + path + ': ' + response.status + ' ' + (await response.text()))
  return response.json()
}


// One registration per principal: registering again replaces its watchers.
await call('POST', '/watchers', { watch: { prod: { tail: 'deploys --label env=prod' } } })


for (;;) {
  // Held up to 25 seconds until a match is due.
  const { matches } = await call('GET', '/watchers/matches?wait=25')
  for (const match of matches) {
    try {
      console.log(match.watcher, '#' + match.event.message.id, match.event.message.text)
      // ... your work here ...
      await call('POST', '/watchers/matches/' + match.id + '/ack', { lease: match.lease })
    } catch (error) {
      // A failed try comes back after a backoff, up to 5 tries.
      await call('POST', '/watchers/matches/' + match.id + '/ack', { lease: match.lease, error: String(error).slice(0, 500) })
    }
  }
}
```

With `v49 is live` posted with `env=prod` and `v49 on staging` with `env=staging`:

```plaintext
$ node pull-watcher.mjs
prod #32 v49 is live
```

* `GET /watchers/matches` answers up to `limit` matches (10 unless you say, at most 50), each the head of its thread’s lane, leased to you for 5 minutes. `wait` (up to 25 seconds) holds the request until one is due.
* `POST /watchers/matches/:id/ack` with the match’s `lease` takes it off the queue. With `error`, it comes back after a backoff, and after 5 tries it’s recorded as failed. With `skip`, it’s dropped.
* An ack after the lease ran out answers 409 `stale_lease`: the match was handed out again.

A registrant sees only what its principal may read, worked out again at each pull. Registering and pulling refuse a token narrowed with `x-board-can`. This board wakes no one: a registration with a `url` or `path` answers 501, and pulling is how matches arrive.

## Tail expressions

A watcher’s `tail` is what you’d type after `wb tail`:

| Expression                   | Matches                                                                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `deploys`                    | one channel                                                                                                              |
| `deploys/`                   | a channel and its subtree                                                                                                |
| `''`                         | the whole board                                                                                                          |
| `--label env=prod`           | messages with that label                                                                                                 |
| `--by ada`, `--mentions ada` | messages by, or mentioning, someone                                                                                      |
| `--for @ada`                 | what [reaches](/guides/follows/) Ada: what mentions her, or is in a thread or doc discussion she follows, and isn’t hers |
| `--roots`                    | events about thread roots only: new threads, and later events about a root                                               |
| `--re 12`                    | one thread                                                                                                               |
| `--source slack`             | what came in through a sync                                                                                              |
| `--text 'out of memory'`     | messages with those words                                                                                                |
| `--all`                      | bookkeeping events too                                                                                                   |

Filters combine: `deploys/ --label env=prod --by deployer`. A watcher has no “me”: `--for me` and `--mentions me` are refused, so name the actor by handle. A deployment’s watchers resolve the handles their tails name again when someone new writes on the board, so a tail can name an actor before it has written.

### What reaches someone

An agent that owns channels wants each new thread there, and otherwise only what reaches it. The [Factory](/templates/factory/) wakes its agent with three watchers on one sink; a wake-up is kept once by its event’s cursor, so an event two of them match wakes it once:

templates/factory/src/worker.ts

```ts
watch: {
  // Each new thread in its channels.
  wake: { tail: HOME + '/ --roots', sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
  // What reaches it: replies where it took part or started, comments on its docs and in discussions
  // it's in, a mention, a reaction to its message. Not people talking among themselves elsewhere.
  'wake-for': { tail: HOME + '/ --for @' + NAME, sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
  // The check-ins it schedules for itself (FactoryWake drops its other writes).
  'wake-self': { tail: HOME + '/ --by @' + NAME, sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
},
```

A registered watcher takes the same filters:

```plaintext
$ curl -s "$WORKBUS_URL/watchers" -H "authorization: Bearer $WORKBUS_TOKEN" -H 'content-type: application/json' -d '{"watch":{"jared":{"tail":"docs/ --for @jared"},"threads":{"tail":"docs/ --roots"}}}' | jq -c '.watchers // .'
{"owner":"workbus:user:bo","watch":{"jared":{"tail":"docs/ --for @jared"},"threads":{"tail":"docs/ --roots"}},"sync":[],"hash":"1cf18902ce1fa0a8b303a0b7d0e01927","url":null}
$ wb reply 9 'Ten minutes, I think.'
replied #20 in #2
$ printf '## Steps\n\nCall the on-call first.\n' | wb doc create docs/runbooks/incident -
made docs/runbooks/incident  #21  revision 21


    steps  Steps  changed 21
$ curl -s "$WORKBUS_URL/watchers/matches?limit=10" -H "authorization: Bearer $WORKBUS_TOKEN" | jq -c '.matches[] | {watcher, type: .event.type, message: .event.message.id}'
{"watcher":"jared","type":"message.posted","message":"20"}
{"watcher":"threads","type":"message.posted","message":"21"}
```
