Skip to main content
OmniCommerce receives marketplace-specific pushes, refreshes the full resource, and publishes one stable integration contract. Consumers such as Spresso.ai do not need to understand Shopee, Lazada, TikTok Shop, Shopify, Zalora, or Amazon payload shapes.
Order events use the standardized 2026-08-01 envelope. Return and settlement events use standardized 2026-08-29 envelopes. Product and look events use the original eventId / eventType envelope. Each event reference identifies its exact contract; do not assume fields from one envelope exist in another.

Create a subscription

Create subscriptions with an organization API key or an OAuth token that has the webhooks:manage scope. The endpoint must be a public HTTP(S) URL.
The 201 response contains the subscription and an omni_whsec_... signing secret.
Store the signing secret when the subscription is created. It is returned only once. Do not put it in source control or application logs.
Manage subscriptions with the Webhooks API. API-key requests inherit their organization from the key and do not send organizationId. See the event catalog for all accepted subscription keys and event availability.

Standardized envelope and versions

Every standardized order, return, or settlement event uses these top-level fields: Unknown additive fields must be ignored. Breaking changes receive a new schemaVersion; existing versions remain stable during their support window. Product and look events use eventId, eventType, organizationId, the resource ID, changedFields, occurredAt, and data. Their reference pages document the complete legacy envelope.

Delivery guarantees

Events are written to the delivery outbox with their immutable resource snapshot. Return any 2xx response only after durably accepting the event.

Verify signatures

Each POST includes:
Calculate HMAC-SHA256 over {timestamp}.{rawBody} with the subscription secret. Compare the hexadecimal digest with X-Omni-Signature using a constant-time comparison before parsing the JSON body.
Keep the request body as raw bytes or text until verification succeeds. Parsing and re-serializing JSON before verification changes the signed value.

Process events safely

  1. Read the raw request body.
  2. Reject missing, stale, or invalid signature headers.
  3. Deduplicate by id, legacy eventId, or X-Omni-Event-Id in durable storage.
  4. For order, return, and settlement events, compare resourceVersion with the last applied version for subject.id.
  5. Apply the complete snapshot in one local transaction.
  6. Persist the event ID and, when present, resource version before returning 2xx.
Buyer PII and delivery addresses are excluded from the standardized order contract. Treat all remaining payload data as organization-confidential.

Continue

Event catalog

Every accepted subscription event and current availability.

Product webhooks

Catalog lifecycle, price, and inventory events.

Order webhooks

Event semantics, field definitions, and payload examples.

Return webhooks

PII-free returned SKUs, refunds, and lifecycle changes.

Settlement webhooks

Marketplace fees, net settlement, and finance-status changes.

Look webhooks

Shoppable-look creation and deletion events.

Marketplace mapping

Provider topics, source identity, and normalization boundaries.