Shopify Webhooks

Shopify Webhooks

Overview

Shopify webhooks deliver real-time event notifications to your app's HTTP endpoints when store events occur — orders placed, products updated, customers created, apps uninstalled. Every webhook payload includes an HMAC-SHA256 signature in the X-Shopify-Hmac-SHA256 header that must be verified before processing. Shopify guarantees at-least-once delivery, so handlers must be idempotent.

When to Use This Skill

• When triggering fulfillment workflows the moment an order is paid
• When syncing product or inventory changes to an external system in near real time
• When sending customer data to a marketing automation platform upon registration
• When cleaning up app data after a merchant uninstalls the app (app/uninstalled)
• When implementing required GDPR webhooks for App Store compliance
• When replacing polling loops that constantly query the Admin API for changes

Core Instructions

1. Register webhooks via the Admin API

Prefer registering webhooks programmatically in the afterAuth hook of your Shopify app. This ensures re-registration after reinstall:

   // Webhook registration helper
   export async function registerWebhooks(adminClient: GraphqlClient, appUrl: string) {
     const webhooksToRegister = [
       { topic: "ORDERS_CREATE", callbackUrl: `${appUrl}/webhooks/orders-create` },
       { topic: "ORDERS_UPDATED", callbackUrl: `${appUrl}/webhooks/orders-updated` },
       { topic: "PRODUCTS_UPDATE", callbackUrl: `${appUrl}/webhooks/products-update` },
       { topic: "APP_UNINSTALLED", callbackUrl: `${appUrl}/webhooks/app-uninstalled` },
       // Mandatory GDPR webhooks
       { topic: "CUSTOMERS_DATA_REQUEST", callbackUrl: `${appUrl}/webhooks/gdpr/customers-data-request` },
       { topic: "CUSTOMERS_REDACT", callbackUrl: `${appUrl}/webhooks/gdpr/customers-redact` },
       { topic: "SHOP_REDACT", callbackUrl: `${appUrl}/webhooks/gdpr/shop-redact` },
     ];

     for (const { topic, callbackUrl } of webhooksToRegister) {
       const response = await adminClient.request(`
         mutation WebhookSubscriptionCreate($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
           webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
             webhookSubscription { id topic }
             userErrors { field message }
           }
         }
       `, {
         variables: {
           topic,
           webhookSubscription: {
             callbackUrl,
             format: "JSON",
           },
         },
       });

       const { userErrors } = response.data.webhookSubscriptionCreate;
       if (userErrors.length > 0) {
         // ALREADY_EXISTS is expected on reinstall — not a real error
         const realErrors = userErrors.filter((e: any) => e.message !== "Address for this topic has already been taken");
         if (realErrors.length > 0) throw new Error(`Webhook registration failed: ${realErrors[0].message}`);
       }
     }
   }

2. Verify the HMAC signature

The most critical step — never process a webhook without verifying its signature:

   // middleware/verify-shopify-webhook.ts
   import crypto from "crypto";

   export function verifyShopifyWebhook(
     rawBody: Buffer,
     hmacHeader: string,
     secret: string
   ): boolean {
     const digest = crypto
       .createHmac("sha256", secret)
       .update(rawBody)
       .digest("base64");

     // Use timingSafeEqual to prevent timing attacks
     try {
       return crypto.timingSafeEqual(
         Buffer.from(digest),
         Buffer.from(hmacHeader)
       );
     } catch {
       return false;
     }
   }

Express middleware example:

   // routes/webhooks.ts (Express)
   import express from "express";
   import { verifyShopifyWebhook } from "../middleware/verify-shopify-webhook";

   const router = express.Router();

   // CRITICAL: Use raw body parser BEFORE json parser for webhook routes
   router.use(
     "/webhooks",
     express.raw({ type: "application/json" }),
     (req, res, next) => {
       const hmac = req.headers["x-shopify-hmac-sha256"] as string;
       if (!verifyShopifyWebhook(req.body, hmac, process.env.SHOPIFY_API_SECRET!)) {
         return res.status(401).send("Unauthorized");
       }
       req.body = JSON.parse(req.body.toString());
       next();
     }
   );

3. Handle webhook events with idempotency

Shopify may deliver the same event multiple times. Use the X-Shopify-Webhook-Id header as an idempotency key:

   router.post("/webhooks/orders-create", async (req, res) => {
     // Respond 200 quickly — Shopify retries if response takes > 5 seconds
     res.status(200).json({ received: true });

     const webhookId = req.headers["x-shopify-webhook-id"] as string;
     const shop = req.headers["x-shopify-shop-domain"] as string;
     const order = req.body;

     // Idempotency check — skip if already processed
     const alreadyProcessed = await db.processedWebhooks.findFirst({
       where: { webhookId, shop },
     });
     if (alreadyProcessed) return;

     // Record processing attempt
     await db.processedWebhooks.create({
       data: { webhookId, shop, topic: "orders/create", processedAt: new Date() },
     });

     // Process the order asynchronously
     await processNewOrder(order, shop);
   });

4. Handle the mandatory GDPR webhooks

Shopify requires these three endpoints for all App Store apps. They must respond 200 even if your app doesn't store personal data:

   router.post("/webhooks/gdpr/customers-data-request", async (req, res) => {
     const { shop_id, shop_domain, customer, orders_requested } = req.body;
     // Return customer data your app has stored for this customer
     await sendCustomerDataReport(shop_domain, customer.id);
     res.status(200).json({ received: true });
   });

   router.post("/webhooks/gdpr/customers-redact", async (req, res) => {
     const { shop_domain, customer } = req.body;
     // Delete all personal data for this customer
     await deleteCustomerData(shop_domain, customer.id);
     res.status(200).json({ received: true });
   });

   router.post("/webhooks/gdpr/shop-redact", async (req, res) => {
     const { shop_domain } = req.body;
     // Delete all store data 48 hours after APP_UNINSTALLED
     await deleteShopData(shop_domain);
     res.status(200).json({ received: true });
   });

5. Monitor delivery failures and set up retry awareness

Shopify retries failed webhooks (non-2xx response or timeout) up to 19 times over 48 hours using exponential backoff. Check delivery health via Admin API:

   export async function getWebhookFailures(adminClient: GraphqlClient) {
     const response = await adminClient.request(`
       query {
         webhookSubscriptions(first: 20) {
           edges {
             node {
               id
               topic
               callbackUrl
               endpoint {
                 ... on WebhookHttpEndpoint {
                   callbackUrl
                 }
               }
             }
           }
         }
       }
     `);
     return response.data.webhookSubscriptions.edges;
   }

Examples

Full order creation handler with error handling and queue

import { Queue, Worker } from "bullmq";

const connection = { host: "localhost", port: 6379 };

const orderQueue = new Queue("order-processing", {
  connection,
  defaultJobOptions: {
    attempts: 3,
    backoff: { type: "exponential", delay: 5000 },
  },
});

router.post("/webhooks/orders-create", async (req, res) => {
  // Must respond within 5 seconds
  res.status(200).json({ received: true });

  const webhookId = req.headers["x-shopify-webhook-id"] as string;
  const shop = req.headers["x-shopify-shop-domain"] as string;

  // Push to queue for reliable async processing
  await orderQueue.add(
    "process-order",
    { order: req.body, shop, webhookId },
    {
      jobId: webhookId, // Prevents duplicate jobs for same webhook
    }
  );
});

const worker = new Worker("order-processing", async (job) => {
  const { order, shop, webhookId } = job.data;
  await syncOrderToERP(order, shop);
  await updateInventoryInWarehouse(order.line_items);
  await sendConfirmationNotification(order);
}, { connection });

List and delete stale webhook subscriptions

export async function cleanupWebhooks(adminClient: GraphqlClient, appUrl: string) {
  const response = await adminClient.request(`
    query {
      webhookSubscriptions(first: 100) {
        edges { node { id callbackUrl topic } }
      }
    }
  `);

  const stale = response.data.webhookSubscriptions.edges.filter(
    ({ node }: any) => !node.callbackUrl.startsWith(appUrl)
  );

  for (const { node } of stale) {
    await adminClient.request(`
      mutation DeleteWebhook($id: ID!) {
        webhookSubscriptionDelete(id: $id) {
          deletedWebhookSubscriptionId
          userErrors { field message }
        }
      }
    `, { variables: { id: node.id } });
  }
}

Best Practices

• Respond 200 within 5 seconds — offload heavy processing to a background queue (Bull, BullMQ, SQS); Shopify marks slow responses as failures and starts retry cycle
• Never trust without verifying HMAC — reject any request that fails signature validation with 401
• Use raw body for HMAC computation — any body parsing before HMAC check corrupts the byte representation and causes false signature failures
• Store `X-Shopify-Webhook-Id` for idempotency — keep a table of processed webhook IDs to prevent double-processing on retries
• Re-register webhooks on every OAuth completion — merchants who reinstall the app get a new session; without re-registration, webhooks point to deleted subscriptions
• Use `EventBridge` or `Pub/Sub` delivery for high volume — Shopify supports delivering webhooks to AWS EventBridge and Google Pub/Sub; these provide built-in retry and ordering guarantees

Common Pitfalls

Related Skills

• @shopify-app-development
• @shopify-admin-api
• @webhook-architecture
• @event-driven-architecture
• @gdpr-compliance

Shopify Webhook Security Middleware

Problem/Feature Description

A merchant platform company has built a Shopify app that receives order, product, and customer events via HTTP webhooks. Their current implementation has been flagging legitimate webhook deliveries as unauthorized, while the security team suspects some forged requests may be slipping through. After investigation, the team suspects the issue is in how the HMAC signatures are being checked.

You have been asked to write a clean, standalone TypeScript module that correctly verifies incoming Shopify webhook requests. The implementation must follow security best practices and handle the request body correctly so that the signature check works reliably. The team will integrate this module into their Express application.

Output Specification

Produce the following files:

• src/middleware/verify-shopify-webhook.ts — The verification function that accepts the raw request body (as a Buffer), the HMAC header value, and the webhook secret, and returns a boolean.
• src/routes/webhooks.ts — An Express router that mounts webhook handling middleware on /webhooks, properly handles the body parsing pipeline, and includes a sample handler for the POST /webhooks/orders-create endpoint. The handler should respond immediately and then log that the order was received.
• README.md — A short explanation of how to integrate this middleware and why certain implementation choices were made.

Reliable Order Event Processing Pipeline

Problem/Feature Description

A growing e-commerce logistics company has built a Shopify app that listens for order creation events and performs several downstream operations: syncing the order to their ERP system, updating warehouse inventory levels, and sending a confirmation notification to the merchant. Occasionally, Shopify delivers the same order event twice (this is expected behavior), causing orders to be synced to the ERP twice and triggering duplicate warehouse updates and notifications. The operations team has also reported that during peak traffic, some webhook deliveries appear to time out before any response is sent.

You need to redesign the order creation webhook handler so that it responds quickly to Shopify, processes orders reliably in the background, and is safe to receive the same event multiple times without side effects.

Output Specification

Produce the following files:

• src/queues/order-queue.ts — TypeScript module that defines and exports a Bull job queue for order processing, including a job processor that calls syncOrderToERP(order, shop), updateInventoryInWarehouse(order.line_items), and sendConfirmationNotification(order) (stub implementations are fine).
• src/handlers/order-create.ts — TypeScript module exporting an Express route handler for the POST /webhooks/orders-create endpoint.
• src/db/processed-webhooks.ts — TypeScript module exporting a simple in-memory or database-backed store with hasProcessed(webhookId, shop) and markProcessed(webhookId, shop, topic) functions.
• README.md — A brief description of how duplicate delivery is handled and how the response timing requirement is met.

Shopify App Webhook Registration Setup

Problem/Feature Description

A startup is launching a Shopify app in the App Store. The app needs to react to events across the merchant's store: when orders are placed (to trigger their fulfillment pipeline), when products are updated (to sync with their inventory system), and when a merchant uninstalls the app (to clean up stored data). Legal has also flagged that the app must comply with Shopify's data privacy requirements before the app can go live.

The engineering team has a working OAuth flow but the webhook subscriptions aren't being set up reliably — especially after merchants reinstall the app. Merchants who reinstall the app are not getting their events delivered, and in one case a merchant's uninstall event was never received, leaving orphaned data in the database. You need to write the webhook registration logic that runs after each OAuth completion.

Output Specification

Produce the following files:

• src/webhooks/register.ts — A TypeScript module exporting a registerWebhooks(adminClient, appUrl) function that registers all required webhook subscriptions via the Shopify Admin GraphQL API.
• src/webhooks/handlers/gdpr.ts — A TypeScript module containing Express route handlers for all required GDPR endpoints.
• README.md — A brief explanation of where registerWebhooks should be called and how GDPR endpoints should be mounted.