Webhooks

Commerce Engine delivers events to HTTPS endpoints you register through the Admin API. Every event family in this section is a separate webhook you can subscribe to; each page documents the exact payload model under payload.properties.

Register a webhook

POST /webhooks on the Admin API — choose the events, get the signing secret once.

Browse events

Orders, Payments, Shipping, Invoices, Carts, Catalog, Coupons & promotions, Customers, Store, Marketplace.

Request format

Every delivery is a POST with a JSON body shaped as WebhookEnvelope. The event-specific model sits at payload.properties; everything around it is common to all events.

{
  "event": "order.created",
  "event_id": "01J9…",          // same across retries — use as your idempotency key
  "delivery_id": "01J9…",       // unique per attempt
  "timestamp": "2026-09-21T07:04:58.869123+00:00",
  "is_test": false,
  "payload": {
    "event": "order.created",
    "event_id": "01J9…",
    "store_id": "your_store_id",
    "store_type": "b2c",
    "user_id": "usr_…",
    "admin_user_id": null,
    "timestamp": "2026-09-21T07:04:58.512345Z",
    "properties": { "order_number": "ORD-1001", "status": "confirmed", "…": "…" }
  }
}

Header	Value
`X-CE-Event`	Event name, identical to `event` in the body
`X-CE-Signature`	`sha256=<hex>` — HMAC-SHA256 of the raw request body, keyed with your webhook secret
`X-CE-Event-ID`	Same as `event_id`
`X-CE-Delivery-ID`	Same as `delivery_id`
`User-Agent`	`CommerceEngine-Webhooks/1.0`

Any custom_headers you set on the subscription are added to every request.

Verify the signature

Compute the HMAC over the raw body bytes — do not re-serialise the JSON — and compare with a constant-time function before you parse anything.

import crypto from "node:crypto";

export function verifyCommerceEngineSignature(rawBody: string, signatureHeader: string | null, secret: string): boolean {
  if (!signatureHeader?.startsWith("sha256=")) return false;
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = signatureHeader.slice("sha256=".length);
  return (
    expected.length === received.length &&
    crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(received, "hex"))
  );
}

import hashlib, hmac

def verify_commerce_engine_signature(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
    if not signature_header or not signature_header.startswith("sha256="):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header[len("sha256="):])

The secret is returned once when you create the subscription. Rotate it with POST /webhooks/{id}/rotate-secret; deliveries are signed with the current secret only, so update your endpoint before rotating.

Respond and retry

Return any 2XX as soon as you have persisted the event — do the real work asynchronously.
Non-2XX responses and timeouts (30 s) are retried three times: after 5 s, 30 s and 5 minutes. Every attempt carries a new delivery_id and the same event_id.
Return 410 Gone to disable the subscription permanently.
Deliveries are at-least-once and may arrive out of order. De-duplicate on event_id and use the timestamps to resolve ordering.

Subscriptions

A store can have up to 5 enabled webhooks. Each subscription lists the events it receives; unknown event names are ignored.
Test any subscribed event with POST /webhooks/{id}/test — the body is a minimal payload with is_test: true. List the event names the platform knows about with GET /webhooks/event-types.
Every delivery attempt is logged; inspect them with GET /webhooks/deliveries, retry one with POST …/deliveries/{delivery_id}/retry, or replay an event with POST /webhooks/{id}/replay-event/{event_id}.

Marketplace-scoped subscriptions

A subscription created with a marketplace_id only receives events whose payload.properties.marketplace_listing[] contains that marketplace — this is how a marketplace follows a seller store’s listings, inventory, warehouses, MS:-prefixed shipment copies and seller invoices. The marketplace → seller direction (seller.order.*, seller.shipment.*) uses an ordinary, unscoped subscription on the marketplace store, because those payloads carry the target in seller_id instead.

Payload models are shared with the REST APIs wherever the shapes match; where an event publishes a snapshot that differs from the API model (for example the compact tombstone sent by *.deleted events), the event page documents the actual fields.

Introduction

Events

Register a webhook

Browse events

Request format

Verify the signature

Respond and retry

Subscriptions

Marketplace-scoped subscriptions

Register a webhook

Browse events

​Request format

​Verify the signature

​Respond and retry

​Subscriptions

​Marketplace-scoped subscriptions

Request format

Verify the signature

Respond and retry

Subscriptions

Marketplace-scoped subscriptions