Every production Shopify app relies on the Shopify webhook API for real-time data synchronisation. Whether you’re building an inventory management integration, an order fulfilment service, or a customer loyalty platform, webhooks are how Shopify tells your app what happened. This guide covers registration via GraphQL, HMAC verification, idempotency patterns, GDPR mandatory topics, and async processing — everything needed to build a robust Shopify webhook API integration in 2026.

Shopify webhook API — event-driven architecture: registration, HMAC verification, idempotent handlers, retry strategy by CodeAtoZ

The Shopify webhook API supports two registration methods: manual via the Partner Dashboard, and programmatic via the GraphQL Admin API. For production apps, always register webhooks programmatically using the webhookSubscriptionCreate mutation so they are set up automatically on every new merchant install. The Shopify webhook documentation covers all available topics and payload formats.

mutation webhookSubscriptionCreate($topic: WebhookSubscriptionTopic!, $callbackUrl: URL!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: {
    callbackUrl: $callbackUrl
    format: JSON
  }) {
    webhookSubscription { id topic callbackUrl }
    userErrors { field message }
  }
}
# Variables:
# { "topic": "ORDERS_CREATE", "callbackUrl": "https://your-app.com/webhooks/orders/create" }

Register all required topics during the app installation OAuth callback. Key topics for most apps include ORDERS_CREATE, ORDERS_UPDATED, PRODUCTS_CREATE, PRODUCTS_UPDATE, and CUSTOMERS_CREATE. In addition to business topics, three GDPR topics are mandatory for all public Shopify apps: CUSTOMERS_DATA_REQUEST, CUSTOMERS_REDACT, and SHOP_REDACT.

Every Shopify webhook API delivery includes an X-Shopify-Hmac-SHA256 header — a base64-encoded HMAC-SHA256 signature computed from the raw request body using your app’s client secret. You must verify this signature before processing any webhook payload. Skipping verification is a critical security vulnerability — any server could spoof webhook deliveries to your endpoint.

import crypto from 'crypto';

export function verifyShopifyWebhook(rawBody: Buffer, hmacHeader: string, secret: string): boolean {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(hmacHeader));
}

// Express middleware — must use express.raw() NOT express.json()
app.post('/webhooks/:topic', express.raw({ type: 'application/json' }), (req, res) => {
  const hmac = req.headers['x-shopify-hmac-sha256'] as string;
  if (!verifyShopifyWebhook(req.body, hmac, process.env.SHOPIFY_CLIENT_SECRET!)) {
    return res.status(401).send('Unauthorized');
  }
  res.status(200).send('OK'); // Respond 200 immediately
  processWebhookAsync(req.params.topic, JSON.parse(req.body.toString()));
});

The Shopify webhook API guarantees at-least-once delivery — the same event may be delivered more than once, especially during retries. Your handlers must be idempotent: processing the same payload twice must produce the same result as processing it once. Use the X-Shopify-Webhook-Id header as a deduplication key. Store processed IDs in Redis with a 24-hour TTL and skip any webhook whose ID is already recorded.

• Check X-Shopify-Webhook-Id before processing — skip if already seen
• Use SETNX in Redis for atomic deduplication with 24-hour TTL
• Design database writes as upserts, not inserts — safe to run twice
• Respond 200 OK within 5 seconds — process heavy work asynchronously
• Use BullMQ or Sidekiq for async job queues — never block the HTTP response
• Shopify retries failed deliveries up to 19 times over 48 hours

All apps listed in the Shopify App Store must implement three GDPR Shopify webhook API topics. These are not optional — failing the review without them blocks your app from going public. The three topics are customers/data_request (a merchant requests customer data export), customers/redact (a customer requests data deletion), and shop/redact (a merchant uninstalls and requests store data deletion). Refer to the Shopify privacy compliance documentation for the full payload spec and required response actions.

For each GDPR topic, your endpoint must log the request and take the appropriate action — exporting data, deleting records, or confirming deletion. Even if your app stores no customer data, you must implement the endpoints and return 200. Our Shopify development team has shipped dozens of App Store-reviewed apps and can implement full GDPR compliance as part of any Shopify webhook API integration. See also our Shopify custom app development guide for the complete app architecture overview.