"/shopify/webhook":
    post:
        tags: [Shopify]
        operationId: shopifyWebhook
        summary: Shopify webhook callback
        description: |
            Inbound webhook from Shopify. Verified by Shopify HMAC — the
            standard `apiKey` / `accessToken` middleware does **not** run
            on this path, and JSON parsing is bypassed (raw body required
            for HMAC verification).

            Drives downstream order ingestion for the factory pipeline.
            See [`docs/data-flows.md#5-shopify-webhook--order`](../../data-flows.md).
        security: []
        requestBody:
            required: true
            description: |
                Raw Shopify webhook body. The handler binds
                `bodyParser.raw({ type: "application/json" })` so the
                request body is received as a `Buffer` (the raw bytes
                are required for HMAC verification before any parsing).
                Logical payload shape varies by `X-Shopify-Topic` (e.g.
                `orders/create`, `orders/updated`, `orders/cancelled`).
            content:
                application/octet-stream:
                    schema: { type: string, format: binary }
        parameters:
            - in: header
              name: X-Shopify-Topic
              required: true
              schema: { type: string }
              description: Webhook topic (e.g. `orders/create`).
            - in: header
              name: X-Shopify-Hmac-Sha256
              required: true
              schema: { type: string }
              description: Base64 HMAC-SHA256 of the raw body, signed with the webhook secret.
            - in: header
              name: X-Shopify-Shop-Domain
              required: false
              schema: { type: string }
        responses:
            "200":
                description: Accepted.
            "401":
                description: HMAC verification failed.
