Test Shopify webhooks locally

Receive Shopify webhooks on your laptop while you build, with a stable HTTPS URL Shopify can reach.

Shopify sends each webhook as an HTTPS POST to a public URL. Your localhost isn't public. Horizon gives it a public URL.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A Shopify app with the Shopify CLI installed
• Your app's client secret, from the Shopify dev dashboard

SHOPIFY_CLIENT_SECRET=your-client-secret

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const received = request.headers.get("x-shopify-hmac-sha256") ?? "";

  const expected = createHmac("sha256", process.env.SHOPIFY_CLIENT_SECRET!)
    .update(rawBody, "utf8")
    .digest("base64");

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const topic = request.headers.get("x-shopify-topic");
  console.log("Verified Shopify webhook:", topic);

  return new Response("OK", { status: 200 });
}

npm run dev

hrzn tunnel http://localhost:3000 -s my-shop-hooks

[webhooks]
api_version = "2024-07"

  [[webhooks.subscriptions]]
  topics = ["orders/create"]
  uri = "https://my-shop-hooks.hrzn.run/api/webhooks/shopify"

shopify app deploy

shopify app webhook trigger \
  --topic orders/create \
  --api-version 2024-07 \
  --delivery-method http \
  --address https://my-shop-hooks.hrzn.run/api/webhooks/shopify \
  --client-secret your-client-secret

Check it worksCopy Anchor Link

The Horizon terminal prints one line per request:

HORIZON: Tunnel connected
  POST | [200] | /api/webhooks/shopify

Your Next.js terminal prints Verified Shopify webhook: orders/create.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

Check these three causes, in order:

1. Raw body. Compute the HMAC over the raw request body. Shopify warns that a body parser such as express.json() parses the body before your verification code runs. In a Next.js route handler, call request.text(), not request.json().
2. Secret. Use your app's client secret, not an API key.
3. Header. Read X-Shopify-Hmac-Sha256. The value is base64-encoded.

If you test with shopify app webhook trigger, pass --client-secret. Without it, the request has no signature header to verify.

Shopify reports a failed deliveryCopy Anchor Link

Return a 200 response fast. Shopify treats any response outside the 200 range, including 3XX, as an error. It has a one-second connection timeout and a five-second timeout for the whole request. Do slow work after you respond.

If Shopify gets no response or an error, it retries 8 times over the next 4 hours. After 8 consecutive failures, it deletes a subscription configured through the Admin API.

Deliveries stopped after you restarted the tunnelCopy Anchor Link

You started the tunnel without -s. The subdomain was random, so the URL in your shopify.app.toml points nowhere. Restart with the same -s value, or update uri and run shopify app deploy again.

Next stepsCopy Anchor Link

• Compare plans on Pricing.