woocommerce-webhooks

WooCommerce Webhook

このスキルを使用する場面

• WooCommerce の Webhook ハンドラーを設定する
• 署名検証の失敗をデバッグする
• WooCommerce のイベントタイプとペイロードを理解する
• 注文、商品、または顧客のイベントを処理する
• WooCommerce ストアと連携する

重要なコード（必ず使用）

WooCommerce の署名検証（JavaScript）

const crypto = require('crypto');

function verifyWooCommerceWebhook(rawBody, signature, secret) {
  if (!signature || !secret) return false;
  
  const hash = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature), 
      Buffer.from(hash)
    );
  } catch {
    return false;
  }
}

Express の Webhook ハンドラー

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

// CRITICAL: Use raw body for signature verification
app.use('/webhooks/woocommerce', express.raw({ type: 'application/json' }));

app.post('/webhooks/woocommerce', (req, res) => {
  const signature = req.headers['x-wc-webhook-signature'];
  const secret = process.env.WOOCOMMERCE_WEBHOOK_SECRET;
  
  if (!verifyWooCommerceWebhook(req.body, signature, secret)) {
    return res.status(400).send('Invalid signature');
  }
  
  const payload = JSON.parse(req.body);
  const topic = req.headers['x-wc-webhook-topic'];
  
  console.log(`Received ${topic} event:`, payload.id);
  res.status(200).send('OK');
});

Next.js API ルート（App Router）

import crypto from 'crypto';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const signature = request.headers.get('x-wc-webhook-signature');
  const secret = process.env.WOOCOMMERCE_WEBHOOK_SECRET;
  
  const rawBody = await request.text();
  
  if (!verifyWooCommerceWebhook(rawBody, signature, secret)) {
    return new Response('Invalid signature', { status: 400 });
  }
  
  const payload = JSON.parse(rawBody);
  const topic = request.headers.get('x-wc-webhook-topic');
  
  console.log(`Received ${topic} event:`, payload.id);
  return new Response('OK', { status: 200 });
}

FastAPI ハンドラー

import hmac
import hashlib
import base64
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

def verify_woocommerce_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    if not signature or not secret:
        return False
    
    hash_digest = hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).digest()
    expected_signature = base64.b64encode(hash_digest).decode()
    
    return hmac.compare_digest(signature, expected_signature)

@app.post('/webhooks/woocommerce')
async def handle_webhook(request: Request):
    raw_body = await request.body()
    signature = request.headers.get('x-wc-webhook-signature')
    secret = os.getenv('WOOCOMMERCE_WEBHOOK_SECRET')
    
    if not verify_woocommerce_webhook(raw_body, signature, secret):
        raise HTTPException(status_code=400, detail='Invalid signature')
    
    payload = await request.json()
    topic = request.headers.get('x-wc-webhook-topic')
    
    print(f"Received {topic} event: {payload.get('id')}")
    return {'status': 'success'}

一般的なイベントタイプ

イベント	発生するタイミング	一般的な用途
order.created	新しい注文が行われたとき	注文確認メールの送信、在庫の更新
order.updated	注文ステータスが変更されたとき	フルフィルメントの追跡、通知の送信
order.deleted	注文が削除されたとき	外部システムのクリーンアップ
product.created	商品が追加されたとき	外部カタログとの同期
product.updated	商品が変更されたとき	価格、在庫の更新
customer.created	新しい顧客が登録されたとき	ウェルカムメールの送信、CRM との同期
customer.updated	顧客情報が変更されたとき	プロフィール、設定の更新

環境変数

WOOCOMMERCE_WEBHOOK_SECRET=your_webhook_secret_key

ヘッダーのリファレンス

WooCommerce の Webhook には、次のヘッダーが含まれます。

• X-WC-Webhook-Signature - HMAC SHA256 署名（base64）
• X-WC-Webhook-Topic - イベントタイプ（例：「order.created」）
• X-WC-Webhook-Resource - リソースタイプ（例：「order」）
• X-WC-Webhook-Event - アクション（例：「created」）
• X-WC-Webhook-Source - ストアの URL
• X-WC-Webhook-ID - Webhook ID
• X-WC-Webhook-Delivery-ID - 一意の配信 ID

ローカル開発

ローカルで Webhook をテストするには、Hookdeck CLI をインストールします。

次に、トンネルを起動します。

npx hookdeck-cli listen 3000 woocommerce --path /webhooks/woocommerce

アカウントは不要です。ローカルトンネルと、リクエストを確認できる Web UI を利用できます。

参考資料

• overview.md - WooCommerce Webhook の概要、一般的なイベントタイプ
• setup.md - WooCommerce 管理画面での Webhook の設定、署名シークレットの取得
• verification.md - 署名検証の詳細と注意点
• examples/ - 各フレームワーク向けの、実行可能な完全なサンプル

推奨：webhook-handler-patterns

本番環境に対応した Webhook ハンドラーを実装するには、webhook-handler-patterns スキルもインストールしてください。以下を利用できます。

• ハンドラーのシーケンス
• 冪等性
• エラー処理
• 再試行ロジック

関連スキル

• stripe-webhooks - HMAC 検証を使用した Stripe の決済 Webhook
• shopify-webhooks - HMAC 検証を使用した Shopify ストアの Webhook
• github-webhooks - GitHub リポジトリの Webhook
• paddle-webhooks - Paddle の請求 Webhook
• webhook-handler-patterns - 冪等性、エラー処理、再試行ロジック
• hookdeck-event-gateway - 本番環境向けの Webhook インフラストラクチャ