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

# Shopify webhooks and observability

> Application-owned HMAC verification, metadata-only ingress observations, duplicate accounting, retention, alerts, and launch checks.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## Goal

Operate webhook endpoints without confusing StackShift delivery observations with application-level authenticity verification.

## Prerequisites

* A connected Shopify app
* Webhook observer enabled by the platform operator
* Application routes that verify Shopify HMAC against the raw request body

## Workflow

<Steps>
  <Step>
    Keep HMAC verification and idempotent business processing in the Shopify application.
  </Step>

  <Step>
    Deploy production and development webhook routes and verify the environment route checks.
  </Step>

  <Step>
    Inspect observed status, latency, topic, API version, environment, and duplicates on the Shopify page or API.
  </Step>

  <Step>
    Respond to failure-rate, repeated-5xx, and stale-API-version launch signals using application logs and Shopify delivery details.
  </Step>
</Steps>

## The application owns authenticity

Follow Shopify’s [webhook delivery verification guidance](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries) and verify the signature over the raw request body before parsing or acting on the event. Return promptly and make event handling idempotent because deliveries can be retried.

StackShift’s list response deliberately reports `verification: app_owned`. A reachable route or a 2xx response cannot prove that the application validated Shopify’s signature.

## Metadata StackShift records

* Approved ingress fields are webhook ID, topic, shop domain, Shopify API version, normalized environment, request path without query string, response status, latency, first/last observation time, and duplicate count.
* Caddy removes request headers and the full request URI from the persisted Shopify access-log entry. Raw bodies, cookies, authorization, and `X-Shopify-Hmac-Sha256` are not part of the observation model.
* Production and isolated development runtimes are scanned incrementally. An event-key prevents replaying the same log line; repeated webhook IDs update duplicate and status counts.
* The API lists the newest 100 observations and returns aggregate total, successful, failed, duplicates, success rate, average/max latency, failures by status/topic, alerts, and last-delivery time.

## Retention and alerts

* Raw observations and detailed status counts are retained for 30 days and pruned by the observer worker; daily rollups preserve aggregate history.
* `WEBHOOK_FAILURE_RATE` opens as a warning when at least 10 routes were observed in 15 minutes and 20% or more returned outside 2xx.
* `WEBHOOK_REPEATED_5XX` opens as critical when at least three observed routes returned 5xx in 15 minutes.
* Open alerts create correlated project operations incidents. They resolve when the threshold no longer applies.
* Launch checks inspect recently observed webhook API versions against Shopify’s current four stable quarterly versions. No observed version remains a pending check, not fabricated success.

## Expected result

<Check>
  The application authenticates every webhook, while StackShift provides metadata-only delivery health without persisting payloads or HMAC values.
</Check>

## Common failures

<Warning>
  * Application verifies the parsed JSON instead of the raw request bytes
  * Webhook handler returns 404 at both `/webhooks/app/uninstalled` and `/webhooks`
  * Observer cannot read access logs from either runtime
  * Non-2xx responses cross an alert threshold
  * Observed webhook API version is stale
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Configure Shopify app hosting" href="/shopify/app-hosting-setup">
    Prepare supported app source, separate Shopify app targets, committed TOML files, credentials, managed databases, and verification.
  </Card>

  <Card title="Shopify app releases and rollbacks" href="/shopify/app-releases-and-rollbacks">
    How backend deployments are coupled to deterministic Shopify configuration and extension releases, retries, and compensation.
  </Card>

  <Card title="Shopify security and troubleshooting" href="/shopify/security-and-troubleshooting">
    Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.
  </Card>
</CardGroup>