Skip to main content
Webhooks call your endpoint when something changes, so you do not have to poll constantly. Each delivery is a small, signed event. Fetch the full resource from the API when the event includes a link.

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:
The value format is 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.
The signing secret is shown once when you create the subscription or rotate the secret. Store it securely; only the last four characters are shown afterwards.

Idempotency and retries

Use the event id 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].

Managing subscriptions

With the webhooks scope you can create, list, update, and delete subscriptions, rotate each subscription’s signing secret, and inspect delivery attempts. Each subscription has its own endpoint URL, event list, and signing secret.
Last modified on July 2, 2026