Events

Event names are stable strings. Payloads evolve additively.

Products

Event	When
product.created	Product created
product.updated	Product or variant material fields changed
product.deleted	Product soft/hard deleted

Orders

Event	When
order.created	Order placed
order.paid	Payment captured / marked paid
order.fulfillment_started	Fulfillment begun
order.fulfilled	Fully fulfilled
order.cancelled	Cancelled
order.refunded	Refund issued (partial/full reflected in payload)
order.return_requested	Return initiated

Customers

Event	When
customer.created	Customer registered / created
customer.updated	Profile updated

Inventory

Event	When
inventory.changed	Stock level changed at a location

Other (expanding)

Event	When
checkout.completed	Checkout finished (may precede order.paid depending on PSP)
media.uploaded	Media asset ready
webhook.test	Manual test ping

Payload conventions

{
  "event": "inventory.changed",
  "timestamp": "2026-08-01T12:00:00Z",
  "api_version": "v1",
  "payload": {
    "sku": "SKU-1",
    "location_id": "sloc_...",
    "quantity": 42,
    "updated_at": "2026-08-01T12:00:00Z"
  }
}

• Unknown fields must be ignored by consumers
• IDs are opaque strings with resource prefixes (prod_, ord_, cus_, …)
• PII in payloads follows merchant privacy settings; never log full payloads in shared systems without controls

Ordering guarantees

• Per resource: best-effort increasing updated_at; not a global total order
• Duplicates possible after retries — use delivery_id / idempotent upserts
• Out-of-order rare under load — compare versions before overwrite