# Follow the catalog's changes

The change feed for exports and anything that wants increments, and signed webhooks.

**The change feed**, for webhooks, exports and anything that wants increments:

```ts function
import { changes } from "@orbcatalog/client/changes";

const feed = changes({ url: "https://catalog.nordgrat.de", key: env.ORBCATALOG_READ_KEY });
let after = await cursors.get("orbcatalog");
for (;;) {
  const page = await feed.page({ after, limit: 100 });
  if (page.status === "cursor_expired") return startFromExport(); // older than 30 days, or of a restored database
  for (const change of page.data) await apply(change); // { sequence, position, kind: "product.published", ref, version, at }
  if (page.next === undefined) break;
  after = page.next;
  await cursors.set("orbcatalog", after);
}
```

A change names what moved and where it sits, never the content; the consumer reads the entity. `product.withdrawn` is the tombstone, `product.scheduled` says a version goes live at its `liveAt`, `product.unscheduled` that it will not after all. One write's changes share a `sequence` and are numbered by `position` (a batch of 1,000 offers is one write); the cursor is opaque and resumes inside a batch. Commit order is feed order, so a cursor never skips a slow transaction. A cursor names its change with the moment it was written, so one whose changes the feed no longer holds is `cursor_expired`, and so is one of another history of the database, rebuilt or restored from a backup, which counts the same places again.

The catalog follows its own feed the same way: purges, OrbSearch's offers, OrbCart's invalidations and each webhook are readers with a cursor of their own, so a destination that is down holds back only itself.

A read key (`rk_…`) opens `GET /v1/changes?after=&limit=` and nothing else, and only its SHA-256 is stored. The feed is never cached (`private, no-store`), and `next` is absent only once a page read nothing, so a reader that stores every `next` resumes right after the last change it saw. An integrator's `429` or `5xx` is sent again, a few times with backoff, as the Source client does.

**Webhooks**, as the family sends events. Adding one is a row of the catalog's settings, under _Settings_ in the admin, and a receiver needs nothing but the catalog's URL:

```ts
import { verifyEvent } from "@orbcatalog/client/changes";

export async function handle(request: Request): Promise<Response> {
  const event = await verifyEvent(request, { url: "https://catalog.nordgrat.de" });
  if (event.type !== "webhook.test" && event.data.kind === "product.published")
    await shop.refresh(event.data.ref, event.id);
  return new Response(null, { status: 204 });
}
```

- **One CloudEvents 1.0 event per change, in the family's envelope** (`Content-Type: application/cloudevents+json`): `type` is the change's kind, `subject` its ref or SKU, `data` the change as the feed has it, `time` when it was written, `environment` the catalog's `ENVIRONMENT` (`live`, `test` or `preview-<name>`), and `source` the origin of its `PUBLIC_URL` (`https://catalog.orbcart.dev` on test), or `urn:orbcatalog:{catalog}:{environment}` without one, so a test catalog's events are never taken for the live one's. A receiver reads the envelope tolerantly: CloudEvents lets a sender add attributes. `id` is its place in the feed and the moment it was written (`2107.0@2026-10-01T07:00:00.000Z`), the same on every attempt and never again in another history of the database, rebuilt or restored from a backup: deduplicate by it. It is the change's cursor too, so a receiver that wants a nightly sync's thousands of offers reads the feed on after it instead.
- **Signed as every family service signs its events** (RFC 9421): `ecdsa-p256-sha256` with the key the catalog publishes at `/.well-known/jwks.json`, `keyid` its `kid` and `tag` `orbcommerce-event`, covering `@method`, `@authority`, `@path`, `@query`, `content-type`, `content-digest` (the body's SHA-256, RFC 9530), `webhook-id` and `webhook-timestamp`. Every attempt is signed anew and counts for five minutes.
- **Keys before signatures.** The owner rotates the signing key with one action in the panel's settings (`POST /panel/signing-keys`). The new key is in the JWKS at once and signs 31 minutes later, once no copy of the JWKS without it can still be kept: ten minutes at the edge and ten of stale-while-revalidate, a minute in a browser, ten in a receiver's library. The key it replaces stays published six minutes more, while its last signatures count. A receiver never sees a key before it can know it, so a rotation needs nobody's help; a second rotation waits until the new key signs.
- **`verifyEvent`** fetches the keys once, keeps them, and asks again for an unknown key at most once a minute, waiting at most five seconds for them (`keysTimeoutSeconds`), on Workers, Node and Deno. It reads a copy of the request, and throws an `EventVerificationError` with the family's codes, OrbCart's too: `signature_missing`, `wrong_purpose`, `unsupported_algorithm`, `missing_component`, `outside_window`, `digest_mismatch`, `body_too_large`, `unknown_key`, `keys_unavailable`, `signature_invalid` or `event_invalid`; answer those with a 4xx. Behind a proxy that rewrites the URL it forwards, its host or its path, pass the URL the catalog sent to as `target`.
- **Delivered as OrbCart delivers**, in order: any `2xx` within 10 seconds takes the event; a redirect is never followed; `429` or `503` with `Retry-After` waits as long as asked, up to an hour; `410 Gone` pauses the destination until the owner resumes it in the panel (_Settings → Webhooks_, where each destination shows how far behind the feed it is and its failure); anything else is tried again after 5 seconds, 1, 5 and 30 minutes, then hourly, until it succeeds or its cursor falls out of the feed's 30 days. Only this destination waits.
- **Signed for Standard Webhooks too,** for a receiver whose language or tool has a [Standard Webhooks](https://www.standardwebhooks.com) library but no RFC 9421: every delivery also carries `webhook-signature`, `v1` (HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{body}`) with the webhook's own secret. The owner copies it in the panel (_Settings → Webhooks_, `GET /panel/webhooks/{name}/secret`) and rolls it there (`POST`); the old secret keeps signing beside the new one for a day. The catalog keeps it sealed, as it keeps its signing keys. A receiver checks with the library of its language, the same call in each: `new Webhook(secret).verify(body, headers)`. RFC 9421 stays the one that covers the address, so `verifyEvent` refuses a delivery replayed to another endpoint; a Standard Webhooks receiver has only its own secret to tell it so.
- **Tried before it counts.** _Send test_ in the panel (`POST /panel/webhooks/{name}/test`) delivers a `webhook.test` event (`data.webhook` names the webhook) now, signed as every delivery, and says what the destination answered; acknowledge it like any event. Each webhook shows its last ten attempts with status and duration; the answer's body is never read. A webhook pointed at the catalog's own **test receiver** (`{PUBLIC_URL}/test-receiver`, or the catalog's own origin without one) shows in the panel the last 20 events it took, their headers and their bodies as they arrived, and whether both signatures held; it keeps only what the catalog signed.