# Events

URL: /code/platform/events · Id: `page:code/platform/events`

> How every Action writes immutable Events to one ordered log, and how Triggers, Watches and webhooks react to them.

An [Event](/business/nouns/event) is the immutable record that something happened, named `Noun.pastTense`, such as `Order.paid`. Every [Action](/business/nouns/action) writes Events, and Events start every [Workflow](/business/nouns/workflow), [Metric](/business/nouns/metric) and outbound delivery.

## One log per namespace
Each [Startup](/business/nouns/startup) has one ordered Event log in [db.sb](/code/platform/db-sb). An Action appends an Event on every status change, from `pending` to `done`, `failed`, `canceled` or `refused`. Model calls, inbound webhooks and [Visits](/business/nouns/visit) land in the same log, in the same order.

The log keeps everything forever. No Event expires and none is deleted; a correction is a new Event that supersedes the old one. Current state is therefore always explainable: every field of every [Thing](/business/nouns/thing) traces to the Events that set it.

## Names
An Event's name comes from its [Verb](/business/nouns/verb). The Verb `pay` on an [Order](/business/nouns/order) emits `Order.paid`; `staff` on a [Role](/business/nouns/role) emits `Role.staffed`. Inherited writes emit `created`, `updated` and `deleted`.

| Verb | Event | Payload |
| --- | --- | --- |
| [publish](/business/nouns/offer/publish) | `Offer.published` | The [Offer](/business/nouns/offer) |
| [pay](/business/nouns/order/pay) | `Order.paid` | The Order |
| [answer](/business/nouns/conversation/answer) | `Conversation.answered` | The [Conversation](/business/nouns/conversation) |
| [register](/business/nouns/domain/register) | `Domain.registered` | The [Domain](/business/nouns/domain) |

The registry derives every name, so an Event never drifts from the Verb that emits it. The [Event reference](/business/events) lists all of them.

## Selectors
One grammar matches Events everywhere: a name, an optional `where` clause, and bindings. [Triggers](/business/nouns/trigger), [Meters](/business/nouns/meter), [Watches](/business/nouns/watch) and [Tasks](/business/nouns/task) that close on an Event all use it.

```ts
const bigOrders = {
  event: 'Order.paid',
  where: { 'order.total.amount': { gte: 1000 } },
}
```

A selector reads the Event payload, so `order.total.amount` is the paid Order's total.

## Triggers
A [Trigger](/business/nouns/trigger) starts a Workflow on an Event, a schedule, or a Thing entering a state. Triggers are records, so a Startup's whole reactive behavior is a query away.

```ts
import { $ } from 'startup-builder'

// The deliver-outcome Workflow starts on this Trigger.
await $.Trigger.create({ event: 'Order.paid' })
```

Every Trigger firing is itself an Action, with its own Events. A Workflow that fails leaves a `failed` Action and the Event that caused it, side by side.

## Watches and webhooks
A [Watch](/business/nouns/watch) delivers matching Events to an outside URL. Each delivery is signed, retried with backoff, and replayable from any point with [replay](/business/nouns/watch/replay).

**Ask**

```text
Add a watch to ShiftNote.
```

**API**

```bash
curl -X POST https://api.sb/shiftnote.app/watches \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selector":"Example selector","url":"https://shiftnote.app"}'
```

```json
{
  "api": "https://api.sb/shiftnote.app",
  "watch": {
    "$id": "https://api.sb/shiftnote.app/watches/watch_1",
    "$type": "Watch",
    "selector": "Example selector",
    "url": "https://shiftnote.app"
  },
  "secret": "whsec_4f9c2a7e1b8d3f6a0c5e9b2d7a4f1c8e",
  "action": {
    "$id": "https://api.sb/shiftnote.app/actions/action_1",
    "operation": "Watch.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/shiftnote.app/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const { watch, secret } = await $.Watch.create({ selector: 'Example selector', url: 'https://shiftnote.app' })
```

**CLI**

```bash
npx startup-builder do Watch.create --json '{"selector":"Example selector","url":"https://shiftnote.app"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Watch.create({ selector: 'Example selector', url: 'https://shiftnote.app' })"
  }
}
```

Inbound webhooks enter through one ingress per Startup. The ingress verifies the sender's signature, writes an Event, and hands it to Triggers. A signal from an [Integration](/business/nouns/integration) is therefore handled like an internal one.

| Term | Kind | Definition |
| --- | --- | --- |
| [Action](/business/nouns/action) | Noun | An Action is one Verb performed by a Worker on a Thing, recorded with its status and every Event it emits. |
| [Event](/business/nouns/event) | Noun | An Event is the immutable record of something that happened to a Thing, named by its Noun and past-tense Verb. |
| [Trigger](/business/nouns/trigger) | Noun | A Trigger is what starts a Workflow: an Event, a schedule, or a Thing entering a state. |
| [Watch](/business/nouns/watch) | Noun | A Watch is an outbound subscription that delivers the Events a selector matches to a URL, signed, retried, and replayable. |
| [Watch.pause](/business/nouns/watch/pause) | Verb | Pause stops a Watch delivering while its Events keep queuing; the platform pauses a Watch whose deliveries fail for three days. |
| [Watch.replay](/business/nouns/watch/replay) | Verb | Replay redelivers a Watch’s Events from a chosen point, signed as they were the first time. |
| [Watch.resume](/business/nouns/watch/resume) | Verb | Resume restarts a paused Watch and delivers the Events it held, oldest first. |
| [Watch.rotate](/business/nouns/watch/rotate) | Verb | Rotate issues a new signing secret for a Watch and signs with both secrets until the old one expires. |

## Next
- [Event reference](/business/events): every Event and the Verb that emits it.
- [Integrations](/code/platform/integrations): outside [Sources](/business/nouns/source) that send and receive Events.
- [Analytics](/systems/data-and-insights/analytics): Metrics computed from Events.