# Events

A workflow can be started, or continued, by something that happened elsewhere.

**Pushed.** `POST /api/events/<workflow>` takes a
[CloudEvent](https://cloudevents.io) — structured (`application/cloudevents+json`),
a batch of up to a hundred (`application/cloudevents-batch+json`), or binary
(`ce-id`, `ce-source`, `ce-type`, `ce-specversion` headers with the data as the
body):

```sh
curl -X POST "$URL/api/events/paid" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/cloudevents+json" \
  -d '{"specversion":"1.0","id":"evt-1","source":"/billing","type":"invoice.paid","data":{"invoice":4021}}'
```

The run is named from the event's `source` and `id`, so an event delivered twice,
as anything that retries will do, finds the run the first delivery started. The
workflow receives the event's `data` as `event`, with `type`, `subject` and `time`
beside it. `app.deliver(workflow, event)` is the same from code. A run of that
workflow stopped at a `wait` step the event matches is continued instead, and
only when none is waiting is a run started.

**Published.** A workflow says which event types start it, and anything in the
app can publish one:

```ts
// workflows/fulfil.ts
export default workflow({
  on: "com.acme.order.placed",
  steps: [{ id: "pack", ask: "Pack order {{event.order}}", agent: "warehouse" }],
});
```

```ts
// functions/checkout.ts
export default fn({
  input: { order: "the order id" },
  run: async ({ order }, { publish }) => {
    await publish?.("com.acme.order.placed", { order });
  },
});
```

`app.publish(event)` and `POST /api/events` do the same with a CloudEvent. Every
workflow that declared the type starts a run, and every run waiting for the
event continues. An event published twice with the same `source` and `id` starts
nothing new, and a step that is retried publishes the same event. The bus is in
this process: types match exactly, with no patterns; a chain of runs publishing
to each other is refused past sixteen deep; and what a publisher read as
untrusted does not mark the runs it starts.

**Pulled.** `app.follow(source, workflow, { signal })` starts a run for every event
a `Source` yields and stores the cursor of the last one handled, so it continues
where it stopped after a restart.

**On time.** A clock is a source:

```ts
import { clock } from "@praecise/harness";

await app.follow(clock("nightly", { cron: "0 2 * * *", zone: "Europe/Lisbon" }), "report", { signal });
await app.follow(clock("poll", { every: 300 }), "sync", { signal });
```

`cron` is five fields, read in `zone` (UTC unless said); `every` is in seconds.
The run receives `scheduled` and `missed`. `catchUp` says what happens to ticks
that fell due while nothing was running: `"latest"` (the default) runs the most
recent and counts the rest in `missed`, `"all"` runs each, `"none"` runs none.
There is no seconds field and no macros such as `@daily`, and nothing follows a
clock unless the app calls `follow`. `cronNext(expression, after, zone)` is the
arithmetic on its own.

**Told.** A run outlives whoever started it, so an app can say what its runs do to
somebody who is not holding a connection open:

```ts
const app = await App.load({
  root,
  notify: { url: "https://ops.example.com/hooks/praecise", secret: process.env.HOOK_SECRET },
});
```

Each run reports `com.praecise.run.started`, `.waiting` (stopped at a gate, with
the step and what is being asked), `.done`, `.failed` and `.cancelled` as
CloudEvents, once per change, except that two processes holding the same run may
each report its cancellation. The event names the run and its status and never carries what the run
produced. A `{ url, secret }` target receives a signed webhook in the
[Standard Webhooks](https://www.standardwebhooks.com) form (`webhook-id`,
`webhook-timestamp`, `webhook-signature`), retried with backoff;
`verifyWebhook(secret, headers, body)` checks one on the receiving side. `notify`
may be a function instead. Delivery happens behind the run and cannot fail it; one
that does not arrive is listed in `app.problems`. `app.onRunChange(listener)`
hears the same changes in this process.

**Described.** `GET /asyncapi.json` is the events the app receives and sends, as
an AsyncAPI 3.1.0 document: the types its workflows start on and wait for, and
the notifications above. `asyncApi(app)` builds it.
