Skip to main content

Signed inventory events

Use POST /catalog/webhooks/v2/commerce/{backend_type} for product/variant/location inventory facts.

Required headers:

  • X-toAI-Signature
  • X-toAI-Timestamp (Unix seconds)
  • X-toAI-Delivery-Id
  • X-toAI-Key-Id
  • X-toAI-Native-Shop

The body contains stable external product, optional variant, and location references; the domain/provenance/source event identity; delivery/business timestamps; and available/reserved quantities.

Canonical signature​

  1. SHA-256 the exact raw body and encode unpadded base64url.
  2. Build the canonical UTF-8 input with LF separators and no trailing LF: version marker, uppercase method, escaped path, normalized backend type, native shop, timestamp, delivery id, key id, body digest.
  3. HMAC-SHA256 with the managed integration secret and encode unpadded base64url.
  4. Send a fresh delivery timestamp/id on a new delivery attempt while keeping source_event_id stable for the logical business event.

The default clock-skew window is 300 seconds. Replay protection and business-event deduplication are separate. Retry 429/503 with exponential backoff and jitter; never change quantities just to force a retry.