メインコンテンツへスキップ

セキュリティ

Webhookの信頼性は、Unicoの配信保証と同様に、エンドポイントの動作にも大きく依存します。このページでは、エンドポイントが遵守すべき3つの不変条件（冪等性、同時実行数制限、エラー率）について説明します。

冪等性​

UnicのWebhook実装は少なくとも1回の配信を保証します。つまり、同じprocessIdに対して同じステータスが複数回通知される可能性があります。エンドポイントは必ず冪等でなければなりません。

推奨パターン:

  1. Webhookが呼び出されるたびに、まずprocessIdがすでに処理済みかどうかを確認します。
  2. 処理済みの場合は、即座に2xxを返します（作業はすでに完了しています）。
  3. 未処理の場合は、ビジネスロジックを実行し、このprocessIdが処理済みであることを記録します。
// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}
この理由

冪等でないエンドポイントが配信のたびにビジネスロジックを実行する場合（例：カードへの課金、メールの送信）、リトライが発生したときに複数回実行されます。Webhookの配信においてリトライは例外ではなく、通常の動作です。

同時実行数制限​

高トラフィック時のスパイクからエンドポイントを保護するため、Webhookを登録する際に同時処理中の配信の最大数（最大: 500）を設定します。

同時実行数制限に達した場合、Unicoは追加の配信をキューに入れ、空き容量ができ次第処理します。リトライと組み合わせることで、継続的なスパイクが新しいWebhookの実効配信時間を延長する可能性があります。

エラー率​

エラー率（200〜299の範囲外のレスポンス）は常に低く保つ必要があります。エンドポイントが大規模にエラーを返し始めると、UnicoはそのエンドポイントのWebhookスループットを自動的に低下させます。リトライメカニズムと組み合わせると、新しいWebhookの実行時間が大幅に増加する可能性があります。

運用上の指針:

  • 自社側で非2xxレスポンスを監視してください。通常のベースラインを超えた継続的なエラー率に対してアラートを設定してください。
  • Webhookハンドラーをクリティカルパスとして扱ってください。スタック内で最も信頼性の高いサービスの一つであるべきです。
  • 計画的なメンテナンスの場合は、503を返すよりもロードバランサーでの受信停止を優先してください。503を含む継続的な非2xxレスポンスは、上記の自動スループットスロットリングを発動させます。エンドポイントが復旧した際に、スループットの低下によってダウンタイム中にキューに溜まったイベントの配信が遅延します。処理できなかったイベントに対して200を返してはいけません。

ステータスのセマンティクス​

stateとlastEventの値のセットは進化可能な設定として扱います:

  • 明示的に処理するステータス / イベントにのみ反応してください。
  • 不明な値はログに記録してください。エラーを発生させてはいけません。
  • 新しいステータスはメジャーバージョン変更なしに追加される場合があります。
最終更新 に