Skip to Content
Integrate

ORBCOMMERCE DOCUMENTATION

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:

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:

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 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.