Shopify Webhooks Skill

orders/create

app/uninstalled

1. Verification (CRITICAL)

HMAC Verification

X-Shopify-Hmac-Sha256

[!IMPORTANT] Always use the raw request body (Buffer) for verification. Parsed JSON bodies may have subtle differences that cause verification to fail.

Node.js Example (Generic)

const crypto = require('crypto');

function verifyWebhook(rawBody, hmacHeader, apiSecret) {
  const digest = crypto
    .createHmac('sha256', apiSecret)
    .update(rawBody, 'utf8')
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(hmacHeader)
  );
}

Remix / Shopify App Template (Recommended)

@shopify/shopify-app-remix

authenticate.webhook

/* app/routes/webhooks.tsx */
import { authenticate } from "../shopify.server";

export const action = async ({ request }) => {
  const { topic, shop, session, admin, payload } = await authenticate.webhook(request);

  if (!admin) {
    // The webhook request was not valid.
    return new Response();
  }

  switch (topic) {
    case "APP_UNINSTALLED":
      if (session) {
        await db.session.deleteMany({ where: { shop } });
      }
      break;
    case "ORDERS_CREATE":
      console.log(`Order created: ${payload.id}`);
      break;
  }

  return new Response();
};

2. Registration

App-specific Webhooks (Recommended)

shopify.app.toml

app/uninstalled

[webhooks]
api_version = "2025-10"

  [[webhooks.subscriptions]]
  topics = [ "app/uninstalled", "orders/create" ]
  uri = "/webhooks"

Shop-specific Webhooks (Advanced)

webhookSubscriptionCreate

• Per-shop customization.
• Topics not supported by config.
• Dynamic runtime registration.

mutation webhookSubscriptionCreate($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
    userErrors {
      field
      message
    }
    webhookSubscription {
      id
    }
  }
}

3. Mandatory Compliance (GDPR)

shopify.app.toml

• customers/data_request

  : Request to export customer data.

• customers/redact

  : Request to delete customer data.

• shop/redact

  : Request to delete shop data (48 hours after uninstall).

[!WARNING] Failure to handle these can result in app removal.

4. Best Practices

• Idempotency: Webhooks can be delivered multiple times. Ensure your processing logic is idempotent (e.g., check if an order has already been processed before taking action).
• Response Time: Respond with a

  200 OK

  immediately (within 5 seconds). Perform long-running tasks asynchronously (e.g., using a background queue).
• App Uninstalled: ALWAYS handle

  app/uninstalled

  to clean up shop data and cancel subscriptions. This webhook acts as the "offboarding" signal.
• App Uninstalled: ALWAYS handle

  app/uninstalled

  to clean up shop data and cancel subscriptions. This webhook acts as the "offboarding" signal.

Common Topics

• APP_UNINSTALLED

  : App removed. Cleanup required.

• ORDERS_CREATE

  : New order placed.

• ORDERS_PAID

  : Order payment status changed to paid.

• PRODUCTS_UPDATE

  : Product details changed.