Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
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

1
Keep HMAC verification and idempotent business processing in the Shopify application.
2
Deploy production and development webhook routes and verify the environment route checks.
3
Inspect observed status, latency, topic, API version, environment, and duplicates on the Shopify page or API.
4
Respond to failure-rate, repeated-5xx, and stale-API-version launch signals using application logs and Shopify delivery details.

​
The application owns authenticity

Follow Shopify’s webhook delivery verification guidance 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

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

​
Common failures

  • 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

Configure Shopify app hosting

Prepare supported app source, separate Shopify app targets, committed TOML files, credentials, managed databases, and verification.

Shopify app releases and rollbacks

How backend deployments are coupled to deterministic Shopify configuration and extension releases, retries, and compensation.

Shopify security and troubleshooting

Credential storage and isolation guarantees, launch-check interpretation, stable failure codes, and a production diagnosis sequence.