Claude CodeでShopify Webhookを受ける — HMAC検証と重複配信の冪等化

## Shopify Webhook受信の規約
 
- 署名検証は、JSON解析前の生ボディ(Buffer)に対して行う
- HMACの比較は `crypto.timingSafeEqual` を使う
- 署名が不正なら 401 を返し、何も処理しない
- 重複排除のキーは `X-Shopify-Webhook-Id`。`X-Shopify-Event-Id` は使わない
- 重複なら処理せず 200 を返す。処理に失敗したら ID を残さず 500 を返す
- 準拠トピック3つを shopify.app.toml の compliance_topics に必ず入れる
- 変更後は `node --test` を実行し、失敗したら直す

// src/webhook.js
import crypto from "node:crypto";
 
export function verifyHmac(rawBody, header, secret) {
  if (!header) return false;
  const digest = crypto.createHmac("sha256", secret).update(rawBody).digest();
  const given = Buffer.from(header, "base64");
  return given.length === digest.length && crypto.timingSafeEqual(given, digest);
}
 
export function createHandler({ secret, seen, process }) {
  return async function handle(headers, rawBody) {
    if (!verifyHmac(rawBody, headers["x-shopify-hmac-sha256"], secret)) {
      return { status: 401 };
    }
    const id = headers["x-shopify-webhook-id"];
    if (!id) return { status: 400 };
    if (!seen.add(id)) return { status: 200, duplicate: true };
    try {
      await process(headers["x-shopify-topic"], JSON.parse(rawBody));
    } catch (e) {
      seen.delete(id);
      return { status: 500 };
    }
    return { status: 200 };
  };
}

// src/store.js
export class SeenStore {
  #ids = new Set();
  add(id) { if (this.#ids.has(id)) return false; this.#ids.add(id); return true; }
  delete(id) { this.#ids.delete(id); }
}

// test/webhook.test.js(抜粋)
import test from "node:test";
import assert from "node:assert/strict";
import crypto from "node:crypto";
import { createHandler } from "../src/webhook.js";
import { SeenStore } from "../src/store.js";
 
const secret = "test-secret";
const sign = (b) => crypto.createHmac("sha256", secret).update(b).digest("base64");
const body = JSON.stringify({ id: 1 });
const hdr = (o = {}) => ({
  "x-shopify-hmac-sha256": sign(body),
  "x-shopify-webhook-id": "w-1",
  "x-shopify-event-id": "e-1",
  "x-shopify-topic": "orders/create",
  ...o,
});
 
test("本文を1バイト変えると署名検証に落ちる", async () => {
  const calls = [];
  const handle = createHandler({
    secret, seen: new SeenStore(), process: async (t) => calls.push(t),
  });
  assert.equal((await handle(hdr(), body + " ")).status, 401);
  assert.equal(calls.length, 0);
});
 
test("Event-Idが同じでもWebhook-Idが違えば別配信として処理する", async () => {
  const calls = [];
  const handle = createHandler({
    secret, seen: new SeenStore(), process: async (t) => calls.push(t),
  });
  await handle(hdr({ "x-shopify-webhook-id": "w-1" }), body);
  await handle(hdr({ "x-shopify-webhook-id": "w-2" }), body);
  assert.equal(calls.length, 2);
});

[webhooks]
api_version = "2026-10"
 
[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "https://app.example.com/webhooks"

#!/bin/bash
# .claude/hooks/check-compliance.sh  (chmod +x が必要。jqを使う)
FILE=$(jq -r '.tool_input.file_path // empty')
case "$FILE" in
  */shopify.app*.toml) ;;
  *) exit 0 ;;
esac
for t in customers/data_request customers/redact shop/redact; do
  grep -q "\"$t\"" "$FILE" || { echo "missing compliance topic: $t" >&2; exit 2; }
done

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-compliance.sh"
          },
          {
            "type": "command",
            "command": "node --test >&2 || exit 2",
            "timeout": 120
          }
        ]
      }
    ]
  }
}