Webhook解説:署名付きペイロードとリトライ

Backend2026-11-15TryQuickToolBox

本番環境でWebhookが壊れる理由

Webhookエンドポイントを構築し、ローカルでテストして、すべてが動作しました。しかし本番環境では、プロバイダーが重複イベントを送信したり、エンドポイントがタイムアウトしたり、攻撃者がリクエストを偽装したりします。突然、統合は信頼性がなく安全でなくなります。

Webhookは概念的にシンプルです—イベントによってトリガーされるHTTPコールバック—が、本番グレードの実装にはセキュリティと信頼性の慎重な処理が必要です。このガイドでは、真正性を検証するための署名付きペイロードと、障害を処理するためのリトライ戦略という2つの重要な側面をカバーします。

Webhookとは何か?

Webhookはユーザー定義のHTTPコールバックです。ソースシステムでイベントが発生すると(例:支払いが成功)、提供したURLにイベントに関するデータを含むHTTP POSTリクエストを送信します。このプッシュモデルはポーリングよりも効率的です。

しかし、Webhookは課題をもたらします:

まずセキュリティに取り組みましょう。

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

署名付きペイロードは共有シークレットを使用してリクエスト本文の暗号署名を作成します。送信者はこの署名をヘッダー(例:X-Signature)に含めます。エンドポイントは署名を再計算して比較します。一致すれば、リクエストは真正です。

HMAC署名の仕組み

ほとんどのプロバイダーはHMAC-SHA256を使用します。署名は共有シークレットを使用して生のリクエスト本文に対して計算されます。フローは次のとおりです:

  1. プロバイダーとコンシューマーが秘密鍵を共有します。
  2. プロバイダーがペイロードを作成し、HMAC-SHA256(secret, payload)を計算してヘッダーで送信します。
  3. コンシューマーがリクエストを受信し、生の本文を読み取り、同じHMACを計算して比較します。

重要:受信した生の本文をそのまま使用してください—JSONを解析して再シリアライズするとバイトが変更され、署名が壊れる可能性があります。

署名検証の実装

Expressを使用したNode.jsの例を次に示します:

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

// Webhookルートには生のボディパーサーを使用
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // イベントを処理
  const event = JSON.parse(req.body);
  // ... イベントを処理
  
  res.status(200).send('OK');
});

タイミング攻撃を防ぐために、常にcrypto.timingSafeEqualのような定数時間比較を使用してください。

その他のセキュリティ考慮事項

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

安全なエンドポイントでも、ネットワークの問題や一時的な障害によりWebhook配信が失敗する可能性があります。堅牢なリトライメカニズムにより、イベントが失われないようにします。

送信側のリトライ戦略

Webhook送信者を構築する場合は、ジッター付きの指数バックオフを実装します。例:

サンダリングハード問題を避けるためにランダムなジッターを追加します。最大試行回数後に停止してアラートを出します。

受信側のベストプラクティス

Webhookコンシューマーとして、送信者のリトライポリシーを制御することはできませんが、エンドポイントを回復力のあるものにすることができます:

冪等性で重複を処理する

Webhookプロバイダーはタイムアウト時にリトライすることが多いため、同じイベントを複数回受信する可能性があります。処理を冪等にします:

データベースの一意インデックスを使用した例:

async function handleEvent(event) {
  try {
    await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
  } catch (err) {
    if (err.code === '23505') { // 一意制約違反
      return; // 既に処理済み
    }
    throw err;
  }
  // イベントを処理
}

比較:Webhookセキュリティアプローチ

アプローチ 長所 短所
HMAC署名 強力な整合性、広くサポート シークレット管理が必要
Basic認証 シンプル 安全性が低い、ヘッダーに認証情報
IP許可リスト 実装が簡単 IPが変更される可能性、堅牢ではない

HMAC署名はWebhookセキュリティのデファクトスタンダードです。

ローカルでWebhookをテストする

ngrokやlocaltunnelなどのツールは、テストのためにローカルサーバーをインターネットに公開します。署名検証とリトライロジックをシミュレートされた障害で常にテストしてください。

WebhookからのJSONペイロードを検査する場合、フォーマットするとデバッグに役立ちます。JSON Formatterを使用して、Webhookペイロードを整形して検証してください。

FAQ

Webhook署名を検証するにはどうすればよいですか?

共有シークレットを使用して生のリクエスト本文のHMACを計算し、定数時間比較関数を使用して署名ヘッダーと比較します。

Webhookエンドポイントがダウンしている場合はどうすればよいですか?

ほとんどのプロバイダーは指数バックオフでリトライします。エンドポイントが迅速に2xxを返し、非同期で処理するようにして、ダウンタイムの影響を最小限に抑えます。

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

危険です。署名がないと、攻撃者がリクエストを偽装できます。常に署名付きペイロードを使用するか、少なくともHTTPS経由でBasic認証を使用してください。

結論

Webhookは強力ですが、セキュリティと信頼性に注意が必要です。HMAC署名検証を実装して真正性を確保し、リトライと重複を適切に処理するようにシステムを設計してください。これらの実践により、Webhook統合は堅牢で本番環境に対応できるようになります。