Shopify Webhooks: Complete Guide with Payload Examples [2025]

[Event in Shopify Store] → [Shopify Webhook System] → [Your Webhook Endpoint] → [Your Application Logic]

curl -X POST "https://your-shop.myshopify.com/admin/api/2025-01/webhooks.json" \
  -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "topic": "orders/create",
      "address": "https://yourdomain.com/webhooks/shopify/orders",
      "format": "json"
    }
  }'

curl -X GET "https://your-shop.myshopify.com/admin/api/2025-01/webhooks.json" \
  -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN"

mutation {
  webhookSubscriptionCreate(
    topic: ORDERS_CREATE
    webhookSubscription: {
      format: JSON,
      callbackUrl: "https://yourdomain.com/webhooks/shopify/orders"
    }
  ) {
    webhookSubscription {
      id
      topic
      format
      endpoint {
        __typename
        ... on WebhookHttpEndpoint {
          callbackUrl
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

[webhooks]
api_version = "2025-01"

[[webhooks.subscriptions]]
topics = ["orders/create", "orders/updated", "orders/paid"]
uri = "https://yourdomain.com/webhooks/shopify/orders"

[[webhooks.subscriptions]]
topics = ["products/create", "products/update", "products/delete"]
uri = "https://yourdomain.com/webhooks/shopify/products"

{
  "webhook": {
    "topic": "orders/create",
    "address": "https://yourdomain.com/webhooks/shopify/orders",
    "format": "json",
    "fields": ["id", "email", "total_price", "line_items"]
  }
}

{
  "id": 5231234567890,
  "admin_graphql_api_id": "gid://shopify/Order/5231234567890",
  "app_id": 1234567,
  "browser_ip": "192.168.1.1",
  "buyer_accepts_marketing": true,
  "cancel_reason": null,
  "cancelled_at": null,
  "cart_token": "c1-1234567890abcdef",
  "checkout_id": 34567890123456,
  "checkout_token": "1234567890abcdef",
  "client_details": {
    "accept_language": "en-US,en;q=0.9",
    "browser_height": 1080,
    "browser_ip": "192.168.1.1",
    "browser_width": 1920,
    "session_hash": null,
    "user_agent": "Mozilla/5.0..."
  },
  "closed_at": null,
  "confirmation_number": "ABC123456",
  "confirmed": true,
  "contact_email": "[email protected]",
  "created_at": "2025-01-24T10:30:00-05:00",
  "currency": "USD",
  "current_subtotal_price": "59.99",
  "current_total_discounts": "10.00",
  "current_total_price": "54.99",
  "current_total_tax": "5.00",
  "customer": {
    "id": 6234567890123,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890",
    "verified_email": true,
    "default_address": {
      "address1": "123 Main St",
      "address2": "Apt 4",
      "city": "San Francisco",
      "province": "California",
      "country": "United States",
      "zip": "94102",
      "phone": "+1234567890"
    }
  },
  "customer_locale": "en",
  "email": "[email protected]",
  "financial_status": "paid",
  "fulfillment_status": null,
  "line_items": [
    {
      "id": 12345678901234,
      "admin_graphql_api_id": "gid://shopify/LineItem/12345678901234",
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "grams": 500,
      "price": "29.99",
      "product_id": 7890123456789,
      "quantity": 2,
      "requires_shipping": true,
      "sku": "TSHIRT-BLK-L",
      "title": "Awesome T-Shirt",
      "variant_id": 40123456789012,
      "variant_title": "Black / Large",
      "vendor": "Awesome Brand",
      "name": "Awesome T-Shirt - Black / Large",
      "properties": []
    }
  ],
  "note": "Please gift wrap this order",
  "note_attributes": [],
  "number": 1234,
  "order_number": 1234,
  "order_status_url": "https://store.myshopify.com/12345678/orders/abc123/authenticate?key=def456",
  "phone": "+1234567890",
  "presentment_currency": "USD",
  "processed_at": "2025-01-24T10:30:00-05:00",
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Main St",
    "address2": "Apt 4",
    "city": "San Francisco",
    "province": "California",
    "country": "United States",
    "zip": "94102",
    "phone": "+1234567890"
  },
  "shipping_lines": [
    {
      "id": 3456789012345,
      "code": "Standard",
      "price": "5.00",
      "source": "shopify",
      "title": "Standard Shipping"
    }
  ],
  "subtotal_price": "59.98",
  "tags": "wholesale, vip",
  "total_discounts": "10.00",
  "total_line_items_price": "59.98",
  "total_price": "54.98",
  "total_tax": "5.00",
  "total_weight": 1000,
  "updated_at": "2025-01-24T10:30:00-05:00"
}

{
  "id": 8901234567890,
  "title": "Premium Wireless Headphones",
  "body_html": "<p>High-quality wireless headphones with noise cancellation.</p>",
  "vendor": "TechBrand",
  "product_type": "Electronics",
  "created_at": "2025-01-24T11:00:00-05:00",
  "updated_at": "2025-01-24T11:00:00-05:00",
  "published_at": "2025-01-24T11:00:00-05:00",
  "handle": "premium-wireless-headphones",
  "status": "active",
  "tags": "audio, wireless, premium",
  "variants": [
    {
      "id": 45678901234567,
      "product_id": 8901234567890,
      "title": "Black",
      "price": "199.99",
      "sku": "HEADPHONE-BLK",
      "position": 1,
      "inventory_policy": "deny",
      "compare_at_price": "299.99",
      "fulfillment_service": "manual",
      "inventory_management": "shopify",
      "option1": "Black",
      "option2": null,
      "option3": null,
      "created_at": "2025-01-24T11:00:00-05:00",
      "updated_at": "2025-01-24T11:00:00-05:00",
      "taxable": true,
      "barcode": "123456789012",
      "grams": 250,
      "weight": 0.25,
      "weight_unit": "kg",
      "inventory_quantity": 100,
      "requires_shipping": true
    }
  ],
  "options": [
    {
      "id": 10123456789012,
      "product_id": 8901234567890,
      "name": "Color",
      "position": 1,
      "values": ["Black", "Silver", "White"]
    }
  ],
  "images": [
    {
      "id": 30123456789012,
      "product_id": 8901234567890,
      "position": 1,
      "created_at": "2025-01-24T11:00:00-05:00",
      "updated_at": "2025-01-24T11:00:00-05:00",
      "width": 2048,
      "height": 2048,
      "src": "https://cdn.shopify.com/s/files/1/0000/0000/0000/products/headphones.jpg",
      "variant_ids": [45678901234567]
    }
  ]
}

{
  "id": 7123456789012,
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "+19876543210",
  "created_at": "2025-01-24T12:00:00-05:00",
  "updated_at": "2025-01-24T12:00:00-05:00",
  "state": "enabled",
  "verified_email": true,
  "accepts_marketing": true,
  "accepts_marketing_updated_at": "2025-01-24T12:00:00-05:00",
  "marketing_opt_in_level": "single_opt_in",
  "tax_exempt": false,
  "tags": "newsletter, vip",
  "currency": "USD",
  "orders_count": 0,
  "total_spent": "0.00",
  "last_order_id": null,
  "note": "VIP customer from trade show",
  "addresses": [
    {
      "id": 8234567890123,
      "customer_id": 7123456789012,
      "first_name": "Jane",
      "last_name": "Smith",
      "company": "Tech Startup Inc",
      "address1": "456 Market St",
      "address2": "Suite 200",
      "city": "New York",
      "province": "New York",
      "country": "United States",
      "zip": "10001",
      "phone": "+19876543210",
      "default": true
    }
  ],
  "default_address": {
    "id": 8234567890123,
    "customer_id": 7123456789012,
    "first_name": "Jane",
    "last_name": "Smith",
    "address1": "456 Market St",
    "city": "New York",
    "province": "New York",
    "country": "United States",
    "zip": "10001",
    "default": true
  }
}

{
  "inventory_item_id": 45678901234567,
  "location_id": 67890123456789,
  "available": 47,
  "updated_at": "2025-01-24T13:00:00-05:00"
}

{
  "id": 4567890123456,
  "order_id": 5231234567890,
  "status": "success",
  "created_at": "2025-01-24T14:00:00-05:00",
  "service": "manual",
  "updated_at": "2025-01-24T14:00:00-05:00",
  "tracking_company": "FedEx",
  "tracking_number": "1234567890",
  "tracking_numbers": ["1234567890"],
  "tracking_url": "https://www.fedex.com/track?number=1234567890",
  "tracking_urls": ["https://www.fedex.com/track?number=1234567890"],
  "receipt": {},
  "line_items": [
    {
      "id": 12345678901234,
      "variant_id": 40123456789012,
      "title": "Awesome T-Shirt",
      "quantity": 2,
      "sku": "TSHIRT-BLK-L",
      "fulfillment_service": "manual",
      "fulfillment_status": "fulfilled"
    }
  ]
}

const crypto = require('crypto');
const express = require('express');
const app = express();

// CRITICAL: Use raw body parser for signature verification
// Must be applied BEFORE any JSON parsing middleware
app.use('/webhooks/shopify', express.raw({ type: 'application/json' }));

app.post('/webhooks/shopify/orders', (req, res) => {
  try {
    // 1. Extract signature from header
    const hmacHeader = req.headers['x-shopify-hmac-sha256'];

    if (!hmacHeader) {
      console.error('Missing HMAC signature header');
      return res.status(401).send('Unauthorized: No signature');
    }

    // 2. Get your app's client secret from environment
    const clientSecret = process.env.SHOPIFY_CLIENT_SECRET;

    if (!clientSecret) {
      console.error('SHOPIFY_CLIENT_SECRET not configured');
      return res.status(500).send('Server configuration error');
    }

    // 3. Compute expected HMAC signature
    const hash = crypto
      .createHmac('sha256', clientSecret)
      .update(req.body, 'utf8')
      .digest('base64');

    // 4. Compare using timing-safe comparison to prevent timing attacks
    const hmacHeaderBuffer = Buffer.from(hmacHeader, 'base64');
    const hashBuffer = Buffer.from(hash, 'base64');

    if (!crypto.timingSafeEqual(hmacHeaderBuffer, hashBuffer)) {
      console.error('HMAC verification failed');
      console.error('Expected:', hash);
      console.error('Received:', hmacHeader);
      return res.status(401).send('Unauthorized: Invalid signature');
    }

    // 5. Signature verified! Parse the payload
    const payload = JSON.parse(req.body.toString('utf8'));

    // Extract metadata from headers
    const shopDomain = req.headers['x-shopify-shop-domain'];
    const topic = req.headers['x-shopify-topic'];
    const webhookId = req.headers['x-shopify-webhook-id'];

    console.log(`Verified webhook from ${shopDomain}: ${topic} (ID: ${webhookId})`);

    // 6. Return 200 immediately to acknowledge receipt
    res.status(200).send('Webhook received');

    // 7. Process webhook asynchronously (don't block response)
    processShopifyWebhookAsync(payload, topic, shopDomain, webhookId);

  } catch (error) {
    console.error('Webhook processing error:', error);
    // Return 200 even on our internal errors to prevent Shopify retries
    res.status(200).send('Webhook received with errors');
  }
});

async function processShopifyWebhookAsync(payload, topic, shopDomain, webhookId) {
  // Your business logic here - runs after response is sent
  // Implement queue-based processing for production
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Shopify webhook server listening on port ${PORT}`);
});

import hmac
import hashlib
import base64
import os
from flask import Flask, request, jsonify

app = Flask(__name__)

# Load client secret from environment
CLIENT_SECRET = os.getenv('SHOPIFY_CLIENT_SECRET')

@app.route('/webhooks/shopify/orders', methods=['POST'])
def shopify_orders_webhook():
    try:
        # 1. Extract signature from header
        hmac_header = request.headers.get('X-Shopify-Hmac-SHA256')

        if not hmac_header:
            app.logger.error('Missing HMAC signature header')
            return 'Unauthorized: No signature', 401

        if not CLIENT_SECRET:
            app.logger.error('SHOPIFY_CLIENT_SECRET not configured')
            return 'Server configuration error', 500

        # 2. Get raw request body (before any parsing)
        raw_body = request.get_data()

        # 3. Compute expected HMAC signature
        hash_obj = hmac.new(
            CLIENT_SECRET.encode('utf-8'),
            raw_body,
            hashlib.sha256
        )
        computed_hmac = base64.b64encode(hash_obj.digest()).decode('utf-8')

        # 4. Compare signatures using timing-safe comparison
        if not hmac.compare_digest(computed_hmac, hmac_header):
            app.logger.error('HMAC verification failed')
            app.logger.error(f'Expected: {computed_hmac}')
            app.logger.error(f'Received: {hmac_header}')
            return 'Unauthorized: Invalid signature', 401

        # 5. Signature verified! Parse JSON payload
        payload = request.get_json()

        # Extract metadata from headers
        shop_domain = request.headers.get('X-Shopify-Shop-Domain')
        topic = request.headers.get('X-Shopify-Topic')
        webhook_id = request.headers.get('X-Shopify-Webhook-Id')

        app.logger.info(f'Verified webhook from {shop_domain}: {topic} (ID: {webhook_id})')

        # 6. Return 200 immediately
        response = jsonify({'status': 'received'})
        response.status_code = 200

        # 7. Process webhook asynchronously
        # In production, use Celery, RQ, or similar queue system
        process_shopify_webhook_async(payload, topic, shop_domain, webhook_id)

        return response

    except Exception as e:
        app.logger.error(f'Webhook processing error: {str(e)}')
        # Return 200 even on internal errors to prevent Shopify retries
        return jsonify({'status': 'received', 'error': True}), 200

def process_shopify_webhook_async(payload, topic, shop_domain, webhook_id):
    # Your business logic here - runs after response
    # Queue this function call in production
    pass

if __name__ == '__main__':
    port = int(os.getenv('PORT', 3000))
    app.run(host='0.0.0.0', port=port)

<?php
// Get client secret from environment
$clientSecret = getenv('SHOPIFY_CLIENT_SECRET');

if (!$clientSecret) {
    error_log('SHOPIFY_CLIENT_SECRET not configured');
    http_response_code(500);
    die('Server configuration error');
}

// 1. Extract signature from header
// PHP converts X-Shopify-Hmac-SHA256 to HTTP_X_SHOPIFY_HMAC_SHA256
$hmacHeader = $_SERVER['HTTP_X_SHOPIFY_HMAC_SHA256'] ?? '';

if (empty($hmacHeader)) {
    error_log('Missing HMAC signature header');
    http_response_code(401);
    die('Unauthorized: No signature');
}

// 2. Get raw POST body (before any parsing)
$rawBody = file_get_contents('php://input');

// 3. Compute expected HMAC signature
$computedHmac = base64_encode(
    hash_hmac('sha256', $rawBody, $clientSecret, true)
);

// 4. Compare signatures using timing-safe comparison
if (!hash_equals($computedHmac, $hmacHeader)) {
    error_log('HMAC verification failed');
    error_log('Expected: ' . $computedHmac);
    error_log('Received: ' . $hmacHeader);
    http_response_code(401);
    die('Unauthorized: Invalid signature');
}

// 5. Signature verified! Parse JSON payload
$payload = json_decode($rawBody, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    error_log('Invalid JSON payload: ' . json_last_error_msg());
    http_response_code(200); // Return 200 to prevent retries
    die('Webhook received with errors');
}

// Extract metadata from headers
$shopDomain = $_SERVER['HTTP_X_SHOPIFY_SHOP_DOMAIN'] ?? '';
$topic = $_SERVER['HTTP_X_SHOPIFY_TOPIC'] ?? '';
$webhookId = $_SERVER['HTTP_X_SHOPIFY_WEBHOOK_ID'] ?? '';

error_log("Verified webhook from $shopDomain: $topic (ID: $webhookId)");

// 6. Return 200 immediately to acknowledge receipt
http_response_code(200);
echo 'Webhook received';

// 7. Process webhook asynchronously
// In production, queue this using Laravel Queue, Symfony Messenger, etc.
processShopifyWebhookAsync($payload, $topic, $shopDomain, $webhookId);

function processShopifyWebhookAsync($payload, $topic, $shopDomain, $webhookId) {
    // Your business logic here
    // Queue this function in production environments
}
?>

# macOS (using Homebrew)
brew install ngrok

# Or download from https://ngrok.com/download

# 1. Start your local server
npm start
# Server running on localhost:3000

# 2. In a new terminal, start ngrok tunnel
ngrok http 3000

# Output shows your public URLs:
# Forwarding  https://abc123.ngrok.io -> http://localhost:3000

# Generated from Webhook Payload Generator
curl -X POST http://localhost:3000/webhooks/shopify/orders \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Hmac-SHA256: nE9nKOHcXsBBEgGYXzqR8H3q6RJZKZb5dLVPVVGdU5M=" \
  -H "X-Shopify-Shop-Domain: test-store.myshopify.com" \
  -H "X-Shopify-Topic: orders/create" \
  -H "X-Shopify-API-Version: 2025-01" \
  -H "X-Shopify-Webhook-Id: b1234567-89ab-cdef-0123-456789abcdef" \
  -d '{"id": 5231234567890, "email": "[email protected]", ... }'

# Install Shopify CLI
npm install -g @shopify/cli

# Create new app (or connect existing)
shopify app init

# Start development server with tunnel
shopify app dev

const express = require('express');
const crypto = require('crypto');
const Queue = require('bull'); // Redis-backed queue
const { Client } = require('pg'); // PostgreSQL client

const app = express();

// Initialize Redis queue for async processing
const shopifyWebhookQueue = new Queue('shopify-webhooks', {
  redis: {
    host: process.env.REDIS_HOST || 'localhost',
    port: process.env.REDIS_PORT || 6379,
  }
});

// PostgreSQL connection for idempotency tracking
const dbClient = new Client({
  connectionString: process.env.DATABASE_URL
});
dbClient.connect();

// CRITICAL: Use raw body parser for webhook routes
// Must be before any other body parsing middleware
app.use('/webhooks/shopify', express.raw({ type: 'application/json' }));

// Other routes can use JSON parser
app.use(express.json());

/**
 * Verify Shopify webhook HMAC signature
 * @param {Buffer} rawBody - Raw request body
 * @param {string} hmacHeader - HMAC signature from header
 * @returns {boolean} - True if signature is valid
 */
function verifyShopifyWebhook(rawBody, hmacHeader) {
  const clientSecret = process.env.SHOPIFY_CLIENT_SECRET;

  if (!clientSecret || !hmacHeader) {
    return false;
  }

  const hash = crypto
    .createHmac('sha256', clientSecret)
    .update(rawBody, 'utf8')
    .digest('base64');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(hash, 'base64'),
      Buffer.from(hmacHeader, 'base64')
    );
  } catch (error) {
    console.error('Signature comparison error:', error);
    return false;
  }
}

/**
 * Check if webhook was already processed (idempotency)
 * @param {string} webhookId - Unique webhook identifier
 * @returns {Promise<boolean>} - True if already processed
 */
async function isWebhookProcessed(webhookId) {
  try {
    const result = await dbClient.query(
      'SELECT 1 FROM processed_webhooks WHERE webhook_id = $1',
      [webhookId]
    );
    return result.rows.length > 0;
  } catch (error) {
    console.error('Database check error:', error);
    // Fail open - allow processing if DB check fails
    return false;
  }
}

/**
 * Mark webhook as processing to prevent duplicates
 * @param {string} webhookId - Unique webhook identifier
 * @param {string} topic - Webhook event type
 * @param {string} shopDomain - Shop that sent webhook
 */
async function markWebhookProcessing(webhookId, topic, shopDomain) {
  try {
    await dbClient.query(
      `INSERT INTO processed_webhooks (webhook_id, topic, shop_domain, status, created_at)
       VALUES ($1, $2, $3, 'processing', NOW())
       ON CONFLICT (webhook_id) DO NOTHING`,
      [webhookId, topic, shopDomain]
    );
  } catch (error) {
    console.error('Failed to mark webhook as processing:', error);
  }
}

/**
 * Main Shopify webhook endpoint
 */
app.post('/webhooks/shopify/:topic', async (req, res) => {
  const startTime = Date.now();

  try {
    // 1. Extract and verify signature
    const hmacHeader = req.headers['x-shopify-hmac-sha256'];

    if (!verifyShopifyWebhook(req.body, hmacHeader)) {
      console.error('Invalid signature from', req.headers['x-shopify-shop-domain']);
      return res.status(401).json({
        error: 'Invalid signature',
        timestamp: new Date().toISOString()
      });
    }

    // 2. Extract metadata
    const shopDomain = req.headers['x-shopify-shop-domain'];
    const topic = req.headers['x-shopify-topic'];
    const apiVersion = req.headers['x-shopify-api-version'];
    const webhookId = req.headers['x-shopify-webhook-id'];

    if (!webhookId) {
      console.error('Missing webhook ID');
      return res.status(400).json({ error: 'Missing webhook ID' });
    }

    // 3. Check for duplicate (idempotency)
    const alreadyProcessed = await isWebhookProcessed(webhookId);

    if (alreadyProcessed) {
      console.log(`Webhook ${webhookId} already processed, skipping`);
      return res.status(200).json({
        received: true,
        duplicate: true,
        webhookId
      });
    }

    // 4. Parse payload after verification
    const payload = JSON.parse(req.body.toString('utf8'));

    // 5. Mark as processing (prevents race conditions)
    await markWebhookProcessing(webhookId, topic, shopDomain);

    // 6. Queue for async processing
    await shopifyWebhookQueue.add(
      {
        webhookId,
        topic,
        shopDomain,
        apiVersion,
        payload,
        receivedAt: new Date().toISOString()
      },
      {
        attempts: 3, // Retry failed jobs 3 times
        backoff: {
          type: 'exponential',
          delay: 2000 // Start with 2 second delay
        },
        removeOnComplete: 100, // Keep last 100 completed jobs
        removeOnFail: false // Keep failed jobs for debugging
      }
    );

    // 7. Return 200 immediately (within 5 second timeout)
    const processingTime = Date.now() - startTime;

    res.status(200).json({
      received: true,
      webhookId,
      processingTime: `${processingTime}ms`
    });

    // 8. Logging
    console.log(`✓ Queued ${topic} webhook from ${shopDomain} (ID: ${webhookId}) in ${processingTime}ms`);

  } catch (error) {
    console.error('Webhook endpoint error:', error);

    // Still return 200 to prevent Shopify retries for our errors
    // Log error for investigation
    res.status(200).json({
      received: true,
      error: true,
      message: 'Webhook received but encountered processing error'
    });
  }
});

/**
 * Process webhooks from queue (runs in background)
 */
shopifyWebhookQueue.process(async (job) => {
  const { webhookId, topic, shopDomain, payload } = job.data;

  console.log(`Processing ${topic} webhook ${webhookId} from ${shopDomain}`);

  try {
    // Route to appropriate handler based on topic
    switch (topic) {
      case 'orders/create':
        await handleOrderCreated(payload, shopDomain);
        break;

      case 'orders/paid':
        await handleOrderPaid(payload, shopDomain);
        break;

      case 'orders/fulfilled':
        await handleOrderFulfilled(payload, shopDomain);
        break;

      case 'products/create':
        await handleProductCreated(payload, shopDomain);
        break;

      case 'products/update':
        await handleProductUpdated(payload, shopDomain);
        break;

      case 'customers/create':
        await handleCustomerCreated(payload, shopDomain);
        break;

      case 'inventory_levels/update':
        await handleInventoryUpdated(payload, shopDomain);
        break;

      case 'app/uninstalled':
        await handleAppUninstalled(shopDomain);
        break;

      // Mandatory GDPR webhooks
      case 'customers/data_request':
        await handleCustomerDataRequest(payload, shopDomain);
        break;

      case 'customers/redact':
        await handleCustomerRedact(payload, shopDomain);
        break;

      case 'shop/redact':
        await handleShopRedact(shopDomain);
        break;

      default:
        console.warn(`Unhandled webhook topic: ${topic}`);
    }

    // Mark as completed
    await dbClient.query(
      `UPDATE processed_webhooks
       SET status = 'completed', completed_at = NOW()
       WHERE webhook_id = $1`,
      [webhookId]
    );

    console.log(`✓ Successfully processed ${topic} webhook ${webhookId}`);

  } catch (error) {
    console.error(`Failed to process webhook ${webhookId}:`, error);

    // Mark as failed
    await dbClient.query(
      `UPDATE processed_webhooks
       SET status = 'failed', error_message = $2, failed_at = NOW()
       WHERE webhook_id = $1`,
      [webhookId, error.message]
    );

    // Re-throw to trigger Bull queue retry
    throw error;
  }
});

/**
 * Business logic handlers
 */
async function handleOrderCreated(order, shopDomain) {
  console.log(`New order #${order.order_number} from ${shopDomain}`);
  console.log(`Customer: ${order.email}`);
  console.log(`Total: ${order.currency} ${order.total_price}`);

  // Example: Send to fulfillment system
  await sendToFulfillmentSystem({
    orderId: order.id,
    orderNumber: order.order_number,
    items: order.line_items.map(item => ({
      sku: item.sku,
      quantity: item.quantity,
      name: item.name
    })),
    shippingAddress: order.shipping_address
  });

  // Example: Send confirmation email
  await sendOrderConfirmationEmail({
    to: order.email,
    orderNumber: order.order_number,
    items: order.line_items,
    total: order.total_price
  });
}

async function handleOrderPaid(order, shopDomain) {
  console.log(`Order #${order.order_number} paid: ${order.currency} ${order.total_price}`);

  // Example: Update accounting system
  await updateAccountingSystem({
    orderId: order.id,
    amount: order.total_price,
    currency: order.currency,
    paymentMethod: order.payment_gateway_names[0]
  });
}

async function handleOrderFulfilled(order, shopDomain) {
  console.log(`Order #${order.order_number} fulfilled`);

  // Example: Send tracking email
  const fulfillments = order.fulfillments || [];

  for (const fulfillment of fulfillments) {
    await sendTrackingEmail({
      to: order.email,
      orderNumber: order.order_number,
      trackingNumber: fulfillment.tracking_number,
      trackingUrl: fulfillment.tracking_url,
      carrier: fulfillment.tracking_company
    });
  }
}

async function handleProductCreated(product, shopDomain) {
  console.log(`New product created: ${product.title}`);

  // Example: Sync to other sales channels
  await syncProductToChannels({
    productId: product.id,
    title: product.title,
    description: product.body_html,
    variants: product.variants,
    images: product.images
  });
}

async function handleProductUpdated(product, shopDomain) {
  console.log(`Product updated: ${product.title}`);

  // Example: Update search index
  await updateSearchIndex({
    productId: product.id,
    title: product.title,
    description: product.body_html,
    tags: product.tags
  });
}

async function handleCustomerCreated(customer, shopDomain) {
  console.log(`New customer: ${customer.email}`);

  // Example: Add to CRM
  await addToCRM({
    customerId: customer.id,
    email: customer.email,
    firstName: customer.first_name,
    lastName: customer.last_name,
    acceptsMarketing: customer.accepts_marketing,
    tags: customer.tags
  });

  // Example: Send welcome email
  if (customer.accepts_marketing) {
    await sendWelcomeEmail({
      to: customer.email,
      firstName: customer.first_name
    });
  }
}

async function handleInventoryUpdated(inventory, shopDomain) {
  console.log(`Inventory updated: Item ${inventory.inventory_item_id} = ${inventory.available}`);

  // Example: Sync inventory to other platforms
  await syncInventoryToMarketplaces({
    inventoryItemId: inventory.inventory_item_id,
    locationId: inventory.location_id,
    available: inventory.available
  });

  // Example: Low stock alert
  if (inventory.available < 10) {
    await sendLowStockAlert({
      inventoryItemId: inventory.inventory_item_id,
      available: inventory.available
    });
  }
}

async function handleAppUninstalled(shopDomain) {
  console.log(`App uninstalled from ${shopDomain}`);

  // Example: Clean up shop data
  await dbClient.query(
    'UPDATE shops SET status = $1, uninstalled_at = NOW() WHERE domain = $2',
    ['uninstalled', shopDomain]
  );
}

// Mandatory GDPR webhooks
async function handleCustomerDataRequest(payload, shopDomain) {
  console.log(`Customer data request for shop ${shopDomain}`);
  // Implement: Gather and provide customer data
}

async function handleCustomerRedact(payload, shopDomain) {
  console.log(`Customer redaction request for shop ${shopDomain}`);
  // Implement: Delete customer data
}

async function handleShopRedact(shopDomain) {
  console.log(`Shop redaction request for ${shopDomain}`);
  // Implement: Delete all shop data
}

/**
 * Placeholder functions for external systems
 * Replace with your actual integrations
 */
async function sendToFulfillmentSystem(data) { /* Your implementation */ }
async function sendOrderConfirmationEmail(data) { /* Your implementation */ }
async function updateAccountingSystem(data) { /* Your implementation */ }
async function sendTrackingEmail(data) { /* Your implementation */ }
async function syncProductToChannels(data) { /* Your implementation */ }
async function updateSearchIndex(data) { /* Your implementation */ }
async function addToCRM(data) { /* Your implementation */ }
async function sendWelcomeEmail(data) { /* Your implementation */ }
async function syncInventoryToMarketplaces(data) { /* Your implementation */ }
async function sendLowStockAlert(data) { /* Your implementation */ }

// Health check endpoint
app.get('/health', (req, res) => {
  res.json({
    status: 'healthy',
    timestamp: new Date().toISOString()
  });
});

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Shopify webhook server listening on port ${PORT}`);
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  console.log('SIGTERM received, closing connections...');
  await shopifyWebhookQueue.close();
  await dbClient.end();
  process.exit(0);
});

CREATE TABLE processed_webhooks (
  webhook_id VARCHAR(255) PRIMARY KEY,
  topic VARCHAR(100) NOT NULL,
  shop_domain VARCHAR(255) NOT NULL,
  status VARCHAR(50) NOT NULL, -- 'processing', 'completed', 'failed'
  error_message TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  completed_at TIMESTAMP,
  failed_at TIMESTAMP,
  INDEX idx_shop_domain (shop_domain),
  INDEX idx_created_at (created_at),
  INDEX idx_status (status)
);

-- Optional: Auto-cleanup old records (keep last 30 days)
CREATE OR REPLACE FUNCTION cleanup_old_webhooks() RETURNS void AS $$
BEGIN
  DELETE FROM processed_webhooks
  WHERE created_at < NOW() - INTERVAL '30 days';
END;
$$ LANGUAGE plpgsql;

// Add debug logging to see exact values
console.log('Received signature:', req.headers['x-shopify-hmac-sha256']);
console.log('Computed signature:', hash);
console.log('Body length:', req.body.length);
console.log('Secret length:', clientSecret.length);

// ❌ WRONG: Blocks response
app.post('/webhooks/shopify', async (req, res) => {
  verifySignature(req);
  await processOrder(req.body); // SLOW
  res.status(200).send('OK');
});

// ✅ CORRECT: Immediate response
app.post('/webhooks/shopify', async (req, res) => {
  verifySignature(req);
  await queue.add(req.body); // FAST
  res.status(200).send('OK');
  // Processing happens in background
});

// Check if already processed
const exists = await db.query(
  'SELECT 1 FROM processed_webhooks WHERE webhook_id = $1',
  [webhookId]
);

if (exists.rows.length > 0) {
  console.log('Already processed:', webhookId);
  return res.status(200).json({ duplicate: true });
}

// Mark as processing (atomic operation)
await db.query(
  `INSERT INTO processed_webhooks (webhook_id, status, created_at)
   VALUES ($1, 'processing', NOW())
   ON CONFLICT (webhook_id) DO NOTHING`,
  [webhookId]
);

// List all webhook subscriptions
const response = await fetch(
  `https://${shop}.myshopify.com/admin/api/2025-01/webhooks.json`,
  {
    headers: {
      'X-Shopify-Access-Token': accessToken
    }
  }
);

const webhooks = await response.json();
console.log('Active webhooks:', webhooks.webhooks.length);

webhooks.webhooks.forEach(wh => {
  console.log(`- ${wh.topic} → ${wh.address}`);
});

// Customer data request
app.post('/webhooks/shopify/gdpr/customers_data_request', async (req, res) => {
  verifySignature(req);
  const { customer, shop_domain } = JSON.parse(req.body);

  res.status(200).send('Request received');

  // Queue job to gather and send customer data
  await gatherCustomerData(customer.id, shop_domain);
});

// Customer redaction
app.post('/webhooks/shopify/gdpr/customers_redact', async (req, res) => {
  verifySignature(req);
  const { customer, shop_domain } = JSON.parse(req.body);

  res.status(200).send('Request received');

  // Queue job to delete customer data
  await deleteCustomerData(customer.id, shop_domain);
});

// Shop redaction
app.post('/webhooks/shopify/gdpr/shop_redact', async (req, res) => {
  verifySignature(req);
  const { shop_domain } = JSON.parse(req.body);

  res.status(200).send('Request received');

  // Queue job to delete all shop data
  await deleteShopData(shop_domain);
});