Webhook解説:署名付きペイロードと信頼性の高いリトライ

Backend2026-11-17TryQuickToolBox

サードパーティサービスを連携し、Webhookをエンドポイントに送信する設定を終えたところでしょう。テストではすべてうまく動作するものの、本番環境ではイベントの欠落、重複配信、さらには偽造リクエストに気づくことがあります。Webhookは概念としてはシンプルですが、正しく実装するのは難しいものです。この記事では、署名付きペイロードでWebhookを安全にする方法と、信頼性の高いリトライロジックを実装して連携を堅牢かつ信頼できるものにする方法を解説します。

Webhookとは何か、なぜ重要なのか

Webhookはイベントによってトリガーされるユーザー定義のHTTPコールバックです。変更をポーリングするAPIの代わりにURLを登録すると、何かが起こるたびにサービスがイベントデータを含むPOSTリクエストを送信します。このプッシュ型モデルはレイテンシとサーバー負荷を削減するため、決済通知、CI/CDトリガー、チャットメッセージなどのリアルタイム連携に最適です。

しかし、Webhookには課題があります。真正性の検証、失敗の処理、そしてexactly-once(正確に一度)の処理を保証することです。これらを一つずつ解決していきましょう。

署名付きペイロードでWebhookを保護する

検証がなければ、誰でも偽のリクエストをWebhookエンドポイントに送信できます。署名付きペイロードは、共有シークレットを使用して生成された暗号署名をリクエストヘッダーに含めることでこれを解決します。署名を検証して、リクエストが想定された送信者から来たものであり、改ざんされていないことを確認します。

HMAC署名の仕組み

ほとんどのサービスはSHA-256を用いたHMAC(Hash-based Message Authentication Code)を使用します。送信者はシークレットを使ってリクエストボディ(場合によってはタイムスタンプも)のハッシュを計算し、X-Signatureのようなヘッダーに含めます。受信側でハッシュを再計算して比較します。

Node.jsでの典型的な検証フローは次のとおりです:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

タイミング攻撃を防ぐため、必ずタイミングセーフな比較を使用してください。また、署名対象データにタイムスタンプを含め、数分以上古いリクエストを拒否することでリプレイ攻撃を防ぎます。

署名検証のベストプラクティス

信頼性の高いリトライを実装する

ネットワークは失敗し、サーバーは再起動し、エンドポイントはタイムアウトします。堅牢なWebhookシステムは失敗した配信をリトライする必要があります。ただし、リトライは重複を引き起こす可能性があるため、冪等性が必要です。

リトライ戦略

ほとんどのプロバイダーはジッター付きの指数バックオフを使用します。たとえば、1分後、5分後、30分後にリトライし、最大試行回数(例:5回)まで行います。受信側が重複排除できるよう、ペイロードに一意のイベントIDを含めます。

受信側では、受信を確認するために2xxステータスですばやく応答し、その後非同期で処理します。処理が失敗した場合、送信者による無期限のリトライに頼ることはできません。独自のデッドレターキューやアラートを実装しましょう。

冪等性キー

重複配信を処理するには、冪等性キー(多くの場合イベントID)を使用し、処理済みのIDを妥当な期間保存します。処理前にIDが既に見られているかを確認し、見られていれば再処理せずに成功を返します。

// 例:Expressでの冪等性チェック
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  await db.seenEvents.add(eventId);
  // イベントを非同期で処理
  res.status(200).send('OK');
});

比較:ポーリング vs Webhook

観点ポーリングWebhook
レイテンシ高い(間隔ベース)低い(ほぼリアルタイム)
サーバー負荷高い(頻繁なリクエスト)低い(イベント駆動)
複雑さ実装が簡単署名検証とリトライが必要
信頼性ポーリング頻度に依存リトライ機構に依存

ステップバイステップ:安全なWebhookレシーバーの構築

  1. エンドポイントを設定する:HTTPS経由でPOSTリクエストを受け付けます。
  2. 署名を検証する:共有シークレットを使用し、無効なリクエストは401で拒否します。
  3. タイムスタンプを確認する:リプレイ攻撃を防ぎます。
  4. 即座に応答する:基本的な検証後に200 OKを返し、その後非同期で処理します。
  5. 冪等性を実装する:イベントIDを使用して重複処理を回避します。
  6. ログと監視を行う:失敗とリトライを記録します。

FAQ

署名付きWebhookペイロードとは何ですか?

署名付きペイロードには暗号署名(通常はHMAC)が含まれており、受信側は共有シークレットを使用してリクエストの真正性と完全性を検証できます。

失敗したWebhookは何回リトライすべきですか?

一般的な慣行は、指数バックオフで3〜5回のリトライです。その後、イベントをデッドレターキューに移動して手動で検査します。

HTTPSなしでWebhookを使用できますか?

いいえ、ペイロードと署名を盗聴や改ざんから保護するためにHTTPSは不可欠です。常にTLSを使用してください。

Webhookペイロードをテストする準備はできましたか?JSON formatterを使って、JSONペイロードをすばやく整形・検証しましょう。