Webhooks

Subscription model

The app uses app-specific webhook subscriptions declared in shopify.app.toml, delivered to a single receiver at /api/webhooks and dispatched by the X-Shopify-Topic header.

Authentication

All webhook requests are verified with HMAC-SHA256 using the Shopify API secret before any handler runs. A failed signature returns 401 and no handler or durable job runs.

Operational topics

Topic	Behavior
`products/update`	Resolves affected collections, finds enabled sorting rules, and enqueues a sorting job.
`inventory_levels/update`	Same ingest as `products/update`, for availability changes.
`orders/paid`	Validates signed cart receipts and records revenue against the A/B assignment for the visitor/variant.
`app_subscriptions/update`	Persists Billing API subscription status changes to the local subscription snapshot.
`shop/update`	Shop resource changes used by the app.

Topic	Behavior
`customers/data_request`	Enqueues a customer data export; merchants download it from the app’s Privacy Exports screen.
`customers/redact`	Deletes matching customer-derived records (metrics, product sales) and scrubs pending-order export snapshots.
`shop/redact`	Deletes all of the shop’s data in foreign-key-safe order.
`app/uninstalled`	Cleans up the shop’s data (same deletion path as `shop/redact`).

Processing model

Webhook handlers stay thin. They verify the signature, resolve affected records, and enqueue work to BullMQ so sorting and cleanup run in the background. Sorting jobs are deduplicated by shop and collection. Completed jobs are retained for 24 hours (or the last 1,000); failed jobs are retained for 7 days.

Merchant outbound webhooks

Advanced-plan merchants can register signed outbound webhooks for sorting jobs, A/B metrics, and dynamic collection updates through the app’s API webhooks screen (/api/merchant-webhooks). Secrets are omitted from list responses.

Start here

Documentation hubs

Legal

Shared legal

Webhooks

Webhooks

Subscription model

Authentication

Operational topics

Processing model

Merchant outbound webhooks

​Webhooks

​Subscription model

​Authentication

​Operational topics

​Compliance topics (GDPR)

​Processing model

​Merchant outbound webhooks

Webhooks

Subscription model

Authentication

Operational topics

Compliance topics (GDPR)

Processing model

Merchant outbound webhooks