Event types
The set is append-only; new event types may be added over time.
Event shape
Events are deliberately thin and carry no personal data. They tell you what changed and where to read it:self_url is present only when the resource can be resolved to a public API URL. When it is present, call it with your read token to get the full, current resource. When it is absent, use the event as a signal to reconcile with the relevant list endpoint.
Verifying the signature
Each delivery includes a signature header:t={unix},v1={hmac_sha256_hex}. Compute HMAC-SHA256 over {timestamp}.{rawBody} using the subscription signing secret, then compare it with v1 using a timing-safe comparison. Use the raw request body exactly as received, before JSON parsing. Once the signature matches, also reject deliveries whose t timestamp is more than five minutes old; because t is part of the signed payload, this stops a captured delivery being replayed later.
Idempotency and retries
Use the eventid to deduplicate work. Delivery is at least once, so your endpoint may receive the same event more than once. Ordering is not guaranteed.
Failed deliveries are retried with increasing backoff for roughly 24 hours. Respond with a 2xx status quickly and do heavier work asynchronously.
If an endpoint keeps rejecting deliveries or becomes unsafe to call, the subscription is disabled and disabled_reason is set. Fix the endpoint, then re-enable the subscription by updating it with active: true.
There is no self-serve replay endpoint. To recover missed events, contact the shop or support, and reconcile by polling list endpoints with filter[updated_since].