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):typeis the change's kind,subjectits ref or SKU,datathe change as the feed has it,timewhen it was written,environmentthe catalog'sENVIRONMENT(live,testorpreview-<name>), andsourcethe origin of itsPUBLIC_URL(https://catalog.orbcart.devon test), orurn: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.idis 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-sha256with the key the catalog publishes at/.well-known/jwks.json,keyiditskidandtagorbcommerce-event, covering@method,@authority,@path,@query,content-type,content-digest(the body's SHA-256, RFC 9530),webhook-idandwebhook-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. verifyEventfetches 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 anEventVerificationErrorwith 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_invalidorevent_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 astarget.- Delivered as OrbCart delivers, in order: any
2xxwithin 10 seconds takes the event; a redirect is never followed;429or503withRetry-Afterwaits as long as asked, up to an hour;410 Gonepauses 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, soverifyEventrefuses 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 awebhook.testevent (data.webhooknames 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.