Webhooks

StockrHub uses Shopify webhooks to stay synchronized with your store in real time. Webhooks are HTTP callbacks that Shopify sends to StockrHub whenever specific events occur in your shop.

Registered Webhooks

StockrHub listens to the following Shopify webhook topics:

Webhook Topic	Purpose
APP_UNINSTALLED	Clean up shop data when the app is uninstalled
ORDERS_CREATE	Track sales for inventory analytics and sales velocity
PRODUCTS_UPDATE	Keep product catalog data in sync
INVENTORY_LEVELS_UPDATE	Sync stock level changes made outside StockrHub

Webhook Registration

Webhooks are registered automatically during app installation. When a merchant completes the OAuth flow and installs StockrHub, the app registers all required webhook subscriptions via the Shopify GraphQL Admin API.

mutation webhookSubscriptionCreate($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
    webhookSubscription {
      id
      topic
      endpoint {
        ... on WebhookHttpEndpoint {
          callbackUrl
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Note

You do not need to manually register or configure webhooks. StockrHub handles all webhook setup automatically. If webhooks become unregistered (e.g., due to a Shopify issue), the app re-registers them on the next authenticated request.

Webhook Verification

Every incoming webhook request is verified before processing to ensure it genuinely came from Shopify.

HMAC Signature Verification

Shopify signs every webhook payload with an HMAC-SHA256 signature using the app’s client secret. StockrHub verifies this signature on every incoming webhook:

1. Extract the signature from the X-Shopify-Hmac-Sha256 header.
2. Compute the expected HMAC by signing the raw request body with the app’s client secret using HMAC-SHA256.
3. Compare signatures using a timing-safe comparison to prevent timing attacks.
4. Reject invalid webhooks — if the signatures do not match, the webhook is rejected with a 401 Unauthorized response.

X-Shopify-Hmac-Sha256: <base64-encoded-hmac>

Caution

Webhook payloads must be verified against the raw request body (before any JSON parsing). Parsing and re-serializing the body can alter the byte sequence and cause HMAC verification to fail.

Retry Behavior

If StockrHub fails to process a webhook (returns a non-2xx status code or times out), Shopify will retry the delivery:

• Shopify retries failed webhooks up to 19 times over a 48-hour period.
• Retry intervals increase exponentially (starting at a few seconds, up to several hours).
• If all retries fail, Shopify may automatically remove the webhook subscription.
• StockrHub re-registers any missing webhooks on the next authenticated request from the merchant.

Tip

StockrHub is designed to process webhooks quickly and return a 200 response as fast as possible. Heavy processing (like Shopify API calls) is handled asynchronously after acknowledging the webhook.

Webhook Data Processing

APP_UNINSTALLED

When it fires: A merchant uninstalls StockrHub from their Shopify store.

What StockrHub does:

1. Identifies the shop from the webhook payload.
2. Removes the shop’s encrypted access token from the database.
3. Cleans up shop-specific data (suppliers, POs, reorder rules, settings).
4. Logs the uninstall event for analytics.

Note

Data cleanup is permanent. If the merchant reinstalls the app, they start fresh with no existing data. Consider exporting important data before uninstalling.

ORDERS_CREATE

When it fires: A new order is placed in the Shopify store (from any sales channel).

What StockrHub does:

1. Extracts line items from the order payload.
2. Records each sold variant and quantity for sales velocity tracking.
3. Updates the sales velocity calculations used by the reorder engine.
4. Checks if any sold items have fallen below their reorder points and generates alerts if so.

This webhook is critical for the sales velocity report and reorder suggestions features. Without it, StockrHub would not know how fast products are selling.

PRODUCTS_UPDATE

When it fires: A product is updated in the Shopify admin (title, description, variants, prices, images, etc.).

What StockrHub does:

1. Extracts the updated product data from the payload.
2. Updates the local product cache in D1 with the latest title, SKU, barcode, and variant information.
3. Ensures that product references in purchase orders and reorder rules reflect the current product data.

This keeps StockrHub’s product catalog in sync with Shopify, so that product names, SKUs, and barcodes are always up to date when searching or creating purchase orders.

INVENTORY_LEVELS_UPDATE

When it fires: Inventory levels change for a product variant at a location (from any source — manual adjustments, other apps, POS, etc.).

What StockrHub does:

1. Identifies the variant and location from the payload.
2. Updates the cached stock level in StockrHub’s database.
3. Evaluates the new stock level against any configured reorder rules.
4. Generates a low stock alert if the stock has fallen below the reorder point.

Note

StockrHub ignores inventory level updates that it caused itself (e.g., from receiving a PO or processing a stock count). This prevents duplicate processing and alert loops.

Webhook Endpoint

All webhooks are delivered to a single endpoint on the StockrHub app:

POST /webhooks

The endpoint inspects the X-Shopify-Topic header to determine which webhook topic was received and routes the payload to the appropriate handler.

Monitoring and Debugging

If you suspect webhooks are not being processed correctly:

1. Check the Shopify admin under Settings > Notifications > Webhooks to see registered webhooks and their delivery status.
2. Review the StockrHub dashboard for any missing or delayed data updates.
3. If webhooks appear to be missing, open StockrHub from the Shopify admin — this triggers a re-registration check for any missing webhook subscriptions.