> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Shopify webhook topics, authentication, and handling for Merchandising & Content Toolkit.

# 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. |

## Compliance topics (GDPR)

| 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.