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 thewebhooks:manage scope. The endpoint must be a public HTTP(S) URL.
201 response contains the subscription and an omni_whsec_... signing
secret.
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:{timestamp}.{rawBody} with the subscription secret.
Compare the hexadecimal digest with X-Omni-Signature using a constant-time
comparison before parsing the JSON body.
Process events safely
- Read the raw request body.
- Reject missing, stale, or invalid signature headers.
- Deduplicate by
id, legacyeventId, orX-Omni-Event-Idin durable storage. - For order, return, and settlement events, compare
resourceVersionwith the last applied version forsubject.id. - Apply the complete snapshot in one local transaction.
- Persist the event ID and, when present, resource version before returning
2xx.
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.