Webhookセキュリティ:HMAC署名、リプレイ攻撃対策、安全な冪等性の実装

Security tutorial - IT technology blog
Security tutorial - IT technology blog

背景と必要性:Webhookエンドポイントに潜むリスク

現代のマイクロサービスアーキテクチャは、外部イベントフックに大きく依存しています。顧客がサブスクリプションを購入したり、カートを決済したり、コードをプッシュしたりするたびに、Stripe、Shopify、GitHubなどのプロバイダーがAPIに対してHTTP POSTペイロードを送信します。

しかし、ここには脆弱性が潜んでいます。こうした受信エンドポイントはパブリックなインターネットに公開し続ける必要がある点です。無防備なルートや開放されたポートは、常に攻撃者のスキャンの対象となります。攻撃者はペイロードを偽造したり、サードパーティゲートウェイになりすましたり、通信データを盗聴したり、バックエンド全体で連鎖的な重複処理を引き起こしたりする可能性があります。

これらのエンドポイントを堅牢化するには、主に3つの重大な攻撃ベクトルを無力化する必要があります。

  • なりすましと改ざん:悪意のある攻撃者が偽造されたイベント(例: 偽のinvoice.paidペイロード)を送信し、不正に注文処理を実行させようとします。これには、共有シークレットキーを用いたHMAC(Hash-based Message Authentication Code)SHA-256署名によって防ぎます。
  • リプレイ攻撃:通信を傍受した攻撃者が、暗号学的に有効な正規のリクエストをキャプチャし、数時間後にサーバーへ再送します。署名検証を通過してしまうと、データベース上で二重にクレジットが付与されたり、商品が二重発送されたりする恐れがあります。これを阻止するため、厳格なタイムスタンプ許容範囲(通常は300秒)を設けます。
  • 重複配信:一時的なネットワーク障害や送信元によるリトライにより、同一のイベントが複数回送信されることがよくあります。一時的な504 Gateway TimeoutによってStripeが1時間に5回リトライした場合でも、ビジネスロジックを5回実行するわけにはいきません。これには、Redisなどのインメモリキャッシュでアトミック操作を用いて冪等性キー(Idempotency Key)を登録することで解決します。

環境構築:前提条件と依存関係のセットアップ

低レイテンシなアトミックロックを実現するために、Node.js 20+、Express、Redis 7を使用して本番環境対応のWebhookレシーバーを構築します。

プロジェクト用のワークスペースを作成します。

mkdir secure-webhook-receiver
cd secure-webhook-receiver
npm init -y

高速なキーバリュ操作を行うためのioredisと、環境変数を管理するためのdotenvをインストールします。

npm install express ioredis dotenv

ローカルでRedisが稼働していない場合は、Dockerを使用してRedisインスタンスを起動します。

docker run -d --name redis-webhook -p 6379:6379 redis:7-alpine

実装と設定:HMAC、タイムスタンプ検証、冪等性の組み込み

Webhookセキュリティにおいて、絶対に守るべき鉄則があります。それは、パース済みのJSONに対して署名検証を行わないことです。ペイロードをパースすると、キーの順序が入れ替わったり、空白が正規化されたり、バイトレベルのフォーマットが失われたりします。こうしたわずかな変化でも、暗号ハッシュは即座に不一致となります。受信した生(raw)のバイトストリームをそのまま保持して検証しなければなりません。

設定変数をローカルの.envファイルに保存します。共有シークレットには、エントロピーの高い文字列(理想的には32バイト/64文字の16進数文字列)が必要です。

PORT=3000
WEBHOOK_SECRET=7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

ハードコードされたシークレットや短い辞書単語を使用すると、オフラインでのブルートフォース攻撃にさらされるリスクがあります。本番環境の認証情報をプロビジョニングする際は、toolcraft.app/ja/tools/security/password-generatorなどのブラウザベースのパスワードジェネレーターを利用して、暗号学的に安全な256ビットの16進数文字列をすばやく生成できます。これはネットワーク通信を伴わずクライアント側のWeb Crypto API上で動作するため、生成されたキーが外部ネットワークへ送信されることはありません。

server.jsに完全な検証エンジンを構築します。

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const Redis = require('ioredis');

const app = express();
const redis = new Redis({
  host: process.env.REDIS_HOST || '127.0.0.1',
  port: parseInt(process.env.REDIS_PORT, 10) || 6379
});

// 暗号署名検証用に生のバイトストリームを保持
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

// 検証ミドルウェア:署名、タイムスタンプのずれ、ペイロードの整合性を検証
function verifyWebhookSignature(req, res, next) {
  const signatureHeader = req.headers['x-webhook-signature'];
  const timestampHeader = req.headers['x-webhook-timestamp'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!signatureHeader || !timestampHeader) {
    return res.status(401).json({ error: 'セキュリティヘッダーが不足しています' });
  }

  // 1. リプレイ攻撃対策:300秒を超えるタイムスタンプの乖離を拒否
  const currentTime = Math.floor(Date.now() / 1000);
  const requestTime = parseInt(timestampHeader, 10);
  const maxToleranceSeconds = 300; // 許容するずれの上限(5分)

  if (isNaN(requestTime) || Math.abs(currentTime - requestTime) > maxToleranceSeconds) {
    return res.status(400).json({ error: 'タイムスタンプが許容範囲外です' });
  }

  // 2. タイムスタンプと生バイトを連結してHMAC SHA-256を計算
  const computedHex = crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.`)
    .update(req.rawBody)
    .digest('hex');

  // 3. サイドチャネルタイミング攻撃を防ぐための一定時間比較
  const signatureBuffer = Buffer.from(signatureHeader, 'hex');
  const expectedBuffer = Buffer.from(computedHex, 'hex');

  if (
    signatureBuffer.length !== expectedBuffer.length ||
    !crypto.timingSafeEqual(signatureBuffer, expectedBuffer)
  ) {
    return res.status(403).json({ error: '無効なWebhook署名です' });
  }

  next();
}

// Redisのアトミックな冪等性ロックを備えた受信ルート
app.post('/api/webhooks/orders', verifyWebhookSignature, async (req, res) => {
  const eventId = req.headers['x-webhook-id'] || req.body.id;

  if (!eventId) {
    return res.status(400).json({ error: '冪等性イベントIDが不足しています' });
  }

  // 4. アトミックロック: Redis SET key value EX 86400 NX
  const idempotencyKey = `webhook:processed:${eventId}`;
  const acquired = await redis.set(idempotencyKey, 'processing', 'EX', 86400, 'NX');

  if (!acquired) {
    // イベントは既に処理中または完了済み。重複して副作用を実行せずに200を返却
    return res.status(200).json({ status: 'ignored', message: 'イベントは既に処理済みか処理中です' });
  }

  try {
    // ビジネスロジックを処理(例: デジタル商品の付与、請求通知など)
    console.log(`イベント ${eventId} を処理中:`, req.body);

    // ステータスを 'processing' から 'completed' に遷移
    await redis.set(idempotencyKey, 'completed', 'EX', 86400);

    return res.status(200).json({ status: 'success', eventId });
  } catch (error) {
    // 予期せぬクラッシュ時はキーを削除し、送信元による再試行が成功するようにする
    await redis.del(idempotencyKey);
    return res.status(500).json({ error: '内部処理エラーが発生しました' });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhookレシーバーがポート ${PORT} で待機中`);
});

動作検証と監視:テストシナリオと本番環境のガードレール

本番トラフィックにエンドポイントを公開する前に、curlを使用したテストで各セキュリティメカニズムを検証します。

1. 有効な署名付きリクエストのテスト

現在のUNIXタイムスタンプとテスト用JSONペイロードを使用し、OpenSSLで有効なHMACハッシュを生成します。

SECRET="7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b7f9b8c2d1e4a5f6e8d0c1b3a5e7f9a2b"
TIMESTAMP=$(date +%s)
PAYLOAD='{"id":"evt_order_9981","type":"payment.succeeded","amount":4900}'

# 有効なHMAC-SHA256署名を生成
SIGNATURE=$(printf "%s.%s" "$TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

# 署名付きペイロードを送信
curl -i -X POST http://localhost:3000/api/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "x-webhook-timestamp: ${TIMESTAMP}" \
  -H "x-webhook-signature: ${SIGNATURE}" \
  -H "x-webhook-id: evt_order_9981" \
  -d "${PAYLOAD}"

レシーバーはHTTP/1.1 200 OKとレスポンスボディ{"status":"success","eventId":"evt_order_9981"}を返します。

2. リプレイ攻撃対策のテスト

攻撃者がキャプチャした通信を再送するシナリオをシミュレートします。10分前(600秒前)のタイムスタンプを生成します。

EXPIRED_TIMESTAMP=$(( $(date +%s) - 600 ))
EXPIRED_SIG=$(printf "%s.%s" "$EXPIRED_TIMESTAMP" "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -i -X POST http://localhost:3000/api/webhooks/orders \
  -H "Content-Type: application/json" \
  -H "x-webhook-timestamp: ${EXPIRED_TIMESTAMP}" \
  -H "x-webhook-signature: ${EXPIRED_SIG}" \
  -H "x-webhook-id: evt_order_9982" \
  -d "${PAYLOAD}"

サーバーは期限切れのタイムスタンプを即座に拒否し、HTTP/1.1 400 Bad Requestと{"error":"タイムスタンプが許容範囲外です"}を返します。

3. 冪等性のテスト

最初のリクエスト(evt_order_9981を含むもの)を再度送信します。Redisに既にキーが存在するため、アプリケーションは処理をスキップして以下を返します。

{"status":"ignored","message":"イベントは既に処理済みか処理中です"}

この保証ひとつで、偶発的な二重請求や不要な在庫の二重引き落としを確実に防ぐことができます。

継続的な監視メトリクス

Prometheus、Datadog、CloudWatchなどで、以下の3つの重要シグナルに関するアラートを設定します。

  • 401/403 エラー率:急激なスパイクは通常、共有シークレットの不一致、ローテーションされたAPI認証情報の同期失敗、あるいは外部からの攻撃試行を示しています。全体トラフィックの0.1%を超える場合は詳細を調査してください。
  • 重複イベントの割合:通常の重複率はベースラインとして1%〜3%程度が想定されます。これが5%を超えて急上昇した場合、後続処理が呼び出し元のタイムアウトしきい値(Stripeは5秒、GitHubは10秒)を超過し、不要な自動リトライが発生している可能性が高いです。
  • P95 受信レイテンシ:Webhookのレスポンス時間は250ms未満に維持してください。データベーストランザクションやサードパーティAPIの呼び出しによって遅延が増大する場合は、受信を受け付けた直後にBullMQ、SQS、RabbitMQなどの非同期キューへ処理をオフロードします。
Share: