Webhook Reliability Playbook

Shopify Webhook Not Arriving

Use this playbook when a merchant action happened in Shopify but the expected event is not visible in Webhook Guard, your endpoint, or a downstream system such as an ERP. The goal is to classify the last stage with evidence instead of assuming Shopify did not send the event.

Written by TechYelp Engineering

missingsubscriptiondeliveryERP
Platform Shopify
Pipeline area Source subscription through final business state
Typical impact Missing order, fulfillment, inventory, customer, or ERP update
Suggested owner Integration engineer with access to Shopify, Webhook Guard, endpoint logs, and downstream system records
Diagnostic complexity High
Recovery risk High if replay could create duplicate orders, shipments, emails, or inventory changes

First five minutes

  • Record the store, topic, business object ID, and approximate trigger time.
  • Check Shopify delivery evidence before concluding the event was never sent.
  • Search Webhook Guard by topic, Webhook Guard event ID, Shopify identifiers, order ID, and received time window.
  • Identify whether any matched integration attempted delivery to the destination endpoint.
  • Avoid broad replay until you know whether downstream processing partially succeeded.

Evidence to collect

Evidence Where to find it What it proves What it does not prove
Shopify delivery log Shopify Dev Dashboard monitoring and logs for the app and topic Shopify attempted delivery, the destination URI, response status, attempt count, response time, and delivery ID That Webhook Guard matched the event, forwarded it, or that the ERP processed it
Webhook Guard event record Webhook Guard Webhook Events list and event detail Webhook Guard received an authenticated event and recorded its headers, topic, Webhook Guard event ID, platform identifiers, payload, and received timestamp That the customer application completed its own database or ERP work
Matched integration Webhook Guard event detail and integration cards The event topic matched one or more configured destinations That every destination accepted or processed the event
Destination delivery attempt Webhook Guard delivery attempt timeline Webhook Guard attempted downstream delivery and captured status, response time, and attempt number That the endpoint's worker committed the business operation after responding
ERP or application record ERP lookup, application trace, database audit table, or worker log The final business state exists or the downstream process reached a known failure Which upstream delivery stage failed without correlation IDs

Focused failure-stage map

Source actionConfirm the merchant action reached the state that should trigger the topic.SubscriptionVerify the expected topic and destination existed at trigger time.Shopify deliveryLook for a Shopify delivery attempt, status, URI, and delivery ID.Webhook Guard intakeSearch for a received event before investigating downstream attempts.
View full pipeline
Shopify Business object and topic trigger Subscription Topic and destination configuration Shopify delivery Delivery ID, status, response time Webhook Guard intake Event record, headers, payload Integration match Matched topic and destination Downstream delivery Attempt status and response Customer processing Queue, worker, transaction Business state ERP, OMS, WMS, or database record

Text equivalent: diagnose the event from source action, subscription, provider delivery, intake, routing, downstream delivery, customer processing, and final business state.

Fast decision tree

  1. Does Shopify show a delivery attempt for the store, topic, and trigger window? If no, inspect subscription existence, topic selection, app installation state, required access, and whether the business action actually occurred.
  2. If Shopify attempted delivery, did Webhook Guard record the event? If no, compare Shopify response status, URI, TLS, DNS, redirects, timeout, and HMAC rejection evidence.
  3. If Webhook Guard recorded the event, did it match the intended integration and topic? If no, inspect integration topic configuration, disabled integrations, and topic naming drift.
  4. If the event was forwarded, did the destination accept it with a 2xx response? If no, use the downstream response body, status, timing, and attempt number to classify the endpoint failure.
  5. If the destination accepted it, did the application complete processing and commit the final business state? If no, investigate worker logs, queue records, database transactions, ERP API responses, and reconciliation state.

Root-cause matrix

Shopify generation and subscription

Possible cause Evidence that supports it Evidence that eliminates it Corrective action
The relevant subscription did not exist or used the wrong topic No Shopify delivery attempt and subscription list lacks the expected topic/destination A Shopify delivery log entry exists for the same topic, store, and resource window Create or correct the subscription through the app configuration path, then trigger a controlled test event.
The merchant action did not reach the state that triggers the selected topic The business object exists but lacks the state transition tied to the topic The event appears in Shopify delivery logs with the expected topic Confirm the desired source-of-truth state and use reconciliation rather than replaying a nonexistent event.

Intake and routing

Possible cause Evidence that supports it Evidence that eliminates it Corrective action
Shopify delivery reached the intake URL but was rejected Shopify log shows non-2xx, timeout, TLS, DNS, redirect, or signature-related failure Webhook Guard has a received event record for the same delivery ID or trigger time Fix the intake boundary shown by Shopify evidence before retrying or recreating subscriptions.
Webhook Guard received the event but no integration matched it Webhook Guard event exists with no matched integration for the topic The event detail shows the intended destination and delivery attempts Enable or update the intended integration topic mapping and decide whether the missed object should be recovered by replay or current-state reconciliation.

Destination and business processing

Possible cause Evidence that supports it Evidence that eliminates it Corrective action
Destination endpoint rejected or timed out Webhook Guard attempt timeline shows 401, 403, 404, 429, 5xx, timeout, or repeated failed attempts Webhook Guard shows a successful downstream 2xx response for the same integration Fix endpoint auth, routing, rate limit, or availability, then retry only affected events after the recovery gate.
Endpoint accepted HTTP delivery but processing failed later Destination returned 2xx, but worker, database, or ERP evidence shows no committed state Downstream record exists with a matching correlation or business key Recover from application or ERP state using idempotent business keys and reconciliation.

Illustrative example — not a real customer incident

Example diagnosis

EvidenceObserved result
Incident evidenceMerchant action occurred.
Incident evidenceNo Shopify delivery attempt exists for the expected topic and time window.
Incident evidenceThe expected subscription is absent or mapped to the wrong topic.
Incident evidenceNo Webhook Guard event exists.

Diagnosis

The problem is subscription or trigger configuration, not Webhook Guard downstream delivery.

Why that diagnosis follows

There is no provider delivery evidence and no Webhook Guard intake record, so the investigation stays before downstream routing or endpoint delivery.

Safest next action

Correct the subscription or topic configuration, trigger a controlled new event, and reconcile the missing business object from current Shopify state if needed.

What not to do

Do not replay an event that was never generated or delivered.

Detailed diagnostic procedure

  1. Start with the Shopify store domain, expected topic, resource ID, and a narrow time window around the merchant action.
  2. Open Shopify delivery logs for the app and topic; record the delivery ID, destination URI, status, response time, and attempt count.
  3. Search Webhook Guard for the Shopify delivery ID, Shopify event correlation ID, topic, and received timestamp. If missing, classify the issue at Shopify delivery or intake.
  4. Open the Webhook Guard event detail and inspect matched integrations. If the expected destination is missing, classify the issue as routing or topic configuration.
  5. Open the destination attempt timeline. Use the first failing status and latest retry status to separate auth, route, timeout, rate-limit, and server failures.
  6. If the destination returned 2xx, trace the application correlation ID, queue message, worker execution, ERP API request ID, and database transaction for the affected business object.

Immediate containment

  • Preserve Shopify and Webhook Guard logs before retention windows or filtering hide the evidence.
  • Pause only the unsafe downstream action if duplicate side effects are still possible.
  • Create a list of affected object IDs instead of replaying an entire time range.
  • Notify the operational owner for the target system if ERP, OMS, WMS, or fulfillment state is missing.

Permanent fix

  • Automate subscription drift checks for required topics and destinations.
  • Require correlation IDs through the intake, queue, worker, database, and downstream API calls.
  • Alert separately for no provider delivery, intake rejection, downstream delivery failure, and business processing failure.
  • Add reconciliation jobs for critical Shopify records so webhook delivery is not the only path to consistency.

Architecture improvement

  • Persist the event before acknowledging receipt.
  • Track delivery status separately from processing status.
  • Use stable business-operation keys for recovery decisions.
  • Make reconciliation a routine control, not an emergency-only script.

Safe recovery gate

  • I confirmed whether Shopify generated a delivery attempt.
  • I confirmed whether the expected subscription and topic existed.
  • I identified whether current-state reconciliation is possible.
  • I know whether a new trigger or backfill is safer than replay.
  • I can verify the final downstream state.

What Webhook Guard can and cannot prove

Can show

  • Whether Webhook Guard received the event.
  • The Webhook Guard event ID, platform identifiers, topic, headers, payload, and received timestamp.
  • Which integrations matched the event.
  • Downstream attempt status, response time, and attempt number.

Cannot prove

  • It cannot prove Shopify generated an event that never reached Webhook Guard without Shopify delivery or subscription evidence.
  • It cannot prove the customer application completed ERP processing after a successful downstream HTTP response.
  • It cannot automatically know whether replay would duplicate an external side effect.

Webhook Guard evidence for this incident

Webhook Guard Event Detail can confirm that Webhook Guard received the event, preserved headers and payload, and matched the intended integration. When no Webhook Guard event exists, Shopify delivery logs are still required to prove whether Shopify generated or attempted delivery.

Limitations

  • No Webhook Guard event cannot prove Shopify never generated a delivery.
  • Webhook Guard cannot show a subscription that never existed at trigger time unless that configuration is recorded elsewhere.

Claim sources

Troubleshoot webhooks · Verify webhook deliveries · Webhook Guard User Guide

User Guide

Open Event Detail guidance

Production runbook

  1. Classify the last confirmed stage.
  2. Identify affected business objects.
  3. Check for partial downstream state.
  4. Choose replay, manual repair, or current-state reconciliation.
  5. Verify final Shopify and downstream state.
  6. Record the incident, recovery action, and prevention work.

Sources and last verification

Sources and verification