Webhook Reliability Playbook

Shopify Order Missing in ERP

Use this playbook when a Shopify order should exist in an ERP, OMS, WMS, or fulfillment system but does not. The recovery goal is to identify how far the order progressed and choose the smallest safe repair.

Written by TechYelp Engineering

ERPorderrecoveryreconciliation
Platform Shopify
Pipeline area End-to-end order synchronization
Typical impact Fulfillment delay, missed order, inventory mismatch, or duplicate ERP order risk
Suggested owner Order integration owner with Shopify, Webhook Guard, application, and ERP access
Diagnostic complexity High
Recovery risk Very high if replay can create duplicate orders, reserve inventory twice, or trigger fulfillment twice

First five minutes

  • Identify the Shopify order, current order state, and intended ERP operation.
  • Search for an existing ERP record under Shopify order ID, order name, external ID, customer, timestamp, and amount.
  • Check Webhook Guard and endpoint evidence before replaying any event.
  • Look for partial side effects: ERP customer, order header, lines, inventory reservation, payment, fulfillment, or tax record.
  • Assign one owner to execute and record the recovery action.

Evidence to collect

Evidence Where to find it What it proves What it does not prove
Shopify order current state Shopify admin or API lookup for the order The current source-of-truth order fields and whether the expected state exists now Which webhook event was delivered or processed earlier
Relevant webhook event Shopify delivery logs and Webhook Guard event detail Whether an order-related event was delivered, received, matched, and forwarded That the ERP accepted or committed the order
ERP lookup ERP search by external ID, order name, customer, timestamp, amount, and line items Whether the order exists, exists partially, or exists under a different identifier Why local sync status failed without application logs
Application mapping and validation result Worker logs, validation errors, mapping tables, and downstream API response Whether SKU, customer, location, tax, currency, or address mapping blocked ERP creation That replay is safe without checking partial side effects

Focused failure-stage map

Shopify order stateConfirm the source order, status, and current fulfillment context.Webhook Guard deliveryFind the received event and downstream attempt status.Customer processingTrace queue, worker, transaction, and local mapping records.ERP stateSearch every known identifier before choosing replay or reconciliation.
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 the Shopify order exist and is it in the state your integration syncs? If no, do not fabricate an ERP order from stale assumptions.
  2. Did Shopify deliver the relevant event and did Webhook Guard receive it? If no, recover from current Shopify state after fixing subscription or delivery.
  3. Did Webhook Guard forward the event to the intended endpoint? If no, fix integration routing or endpoint delivery before recovery.
  4. Did the customer application call the ERP? If no, inspect queue, worker, validation, and mapping failures.
  5. Does any ERP record already exist under another identifier or partial state? If yes, reconcile or repair that record before replay.
  6. If no side effect occurred and the operation is idempotent, recover the smallest affected scope.

Root-cause matrix

Source and delivery

Possible cause Evidence that supports it Evidence that eliminates it Corrective action
Wrong topic or missing subscription No order-related delivery evidence and subscription does not include the relevant order topic Shopify delivery log and Webhook Guard event exist for the order Correct the subscription and recover from current Shopify order state.
Webhook received but not matched to ERP integration Webhook Guard shows event with no intended integration match Event detail shows delivery attempts to the ERP integration endpoint Fix topic mapping and decide whether to replay the event or run order reconciliation.

ERP processing

Possible cause Evidence that supports it Evidence that eliminates it Corrective action
ERP rejected the order Downstream response or worker log shows auth, rate limit, validation, SKU, customer, location, tax, currency, or address error ERP order exists with matching external ID and lines Fix the failing mapping or credential, then retry only the affected order with idempotency.
ERP order was created but local status update failed ERP record exists but local sync database has failed or missing status No ERP record exists under any related identifier Backfill local status from the ERP record instead of creating another order.

Illustrative example — not a real customer incident

Example diagnosis

EvidenceObserved result
Incident evidenceShopify delivery succeeded.
Incident evidenceWebhook Guard delivered the event and received HTTP 200.
Incident evidenceERP lookup by the expected local mapping returns nothing.
Incident evidenceERP lookup by Shopify order reference finds an existing partial order.
Incident evidenceThe local sync-status transaction rolled back.

Diagnosis

The ERP operation partially succeeded, but local state did not record completion.

Why that diagnosis follows

The external ERP record exists under a Shopify reference even though the local mapping is missing, so replaying create-order risks a duplicate.

Safest next action

Reconcile the existing ERP order, repair local mapping/status, and verify inventory and fulfillment before any replay.

What not to do

Do not replay the create-order operation blindly.

Detailed diagnostic procedure

  1. Identify the Shopify order and verify its current status, financial state, fulfillment state, line items, customer, currency, tax, address, and location fields.
  2. Identify the event or synchronization action that should have created the ERP order.
  3. Use Shopify and Webhook Guard evidence to determine how far the event progressed.
  4. Search the ERP using all plausible identifiers before declaring the order missing.
  5. Check for partial side effects such as customer creation, inventory reservation, order header creation, or failed line-item creation.
  6. Choose replay only if the operation is idempotent and no duplicate side effect will occur; otherwise fetch current Shopify state and reconcile.
  7. Verify ERP order, inventory, fulfillment, and customer state after recovery.

Immediate containment

  • Flag the order for manual operational review so fulfillment does not proceed from incomplete data.
  • Pause duplicate-producing recovery scripts.
  • Create a scoped list of affected orders by time window, topic, integration, and failure signature.

Permanent fix

  • Persist Shopify order IDs and ERP external IDs in a durable mapping table.
  • Validate required ERP mappings before acknowledging final processing success.
  • Add reconciliation that can create, repair, or mark exceptions from current Shopify state.

Architecture improvement

  • Model order sync as a state machine with explicit received, validated, submitted, accepted, committed, failed, and reconciled states.
  • Use idempotent create-or-update semantics where the ERP supports them.
  • Add alerts for order events delivered successfully but not reflected in ERP within the expected operational window.

Safe recovery gate

  • I verified the current Shopify order state.
  • I searched the ERP under all known identifiers.
  • I checked for partial side effects.
  • I verified inventory implications.
  • I verified fulfillment implications.
  • I verified customer mapping.
  • I checked payment or refund implications.
  • I have an idempotency key for the recovery operation.
  • I can verify the final Shopify and ERP state.
  • I can record an operator audit note.

What Webhook Guard can and cannot prove

Can show

  • Whether the order-related event reached Webhook Guard.
  • Which integration received delivery attempts and what the endpoint returned.
  • The event history needed to select a narrow recovery set.

Cannot prove

  • It cannot prove the ERP created or rejected an order after a successful endpoint response unless the downstream system reports that state.
  • It cannot determine by itself whether current-state reconciliation is safer than replay for your ERP.

Webhook Guard evidence for this incident

Webhook Guard filters, Event Detail, and downstream attempt history help identify the smallest affected event set before retry or reconciliation.

Limitations

  • Event history cannot determine automatically whether an ERP record already exists under another identifier.
  • Webhook Guard cannot decide whether replay or current-state reconciliation is safer without ERP and business-state evidence.

Claim sources

Webhook Guard User Guide · Troubleshoot webhooks

User Guide

Open Events List guidance · Open Event Detail guidance · Open Delivery Attempts guidance

Production runbook

  1. Identify Shopify order and current state.
  2. Find event and delivery evidence.
  3. Determine farthest completed stage.
  4. Check ERP for existing or partial records.
  5. Pass the recovery gate.
  6. Recover narrowly.
  7. Verify related inventory, fulfillment, and customer state.
  8. Record the incident and corrective action.

Sources and last verification

Sources and verification