このページは機械翻訳です。英語版がソースであり、より正確または最新の場合があります。 英語で表示

知っておくとよいこと - Webhook の制限事項とシステム挙動

finlight が webhook のエラー、再試行、制限をどのように扱うかを理解すると、より信頼性の高い統合を構築し、クォータを効果的に管理できます。

再試行システム挙動

エラー処理と再試行

再試行ロジック

webhook の配信が失敗すると、finlight はリクエストを自動的に再試行します：

再試行スケジュール:

  • 1 回目の再試行: 最初の失敗の直後
  • 2 回目の再試行
  • 3 回目の再試行

最大試行回数:

  • webhook イベントごとに合計 3 回の配信試行
  • 各再試行は同じペイロードとヘッダーを使用します
  • すべての再試行は呼び出し履歴に記録されます

再試行をトリガーするもの

再試行は次の場合に発生します：

  • HTTP エラーコード 4xx および 5xx の応答
  • ネットワークタイムアウト（5 秒の制限）
  • 接続の失敗（DNS エラー、接続拒否）
  • SSL/TLS エラー（証明書の問題）

再試行をトリガーしないもの

次の場合は再試行されません：

  • HTTP 2xx 応答（成功とみなされる）
  • 無効な webhook 構成（不正な URL）
  • 無効化された webhook
自動無効化失敗保護

自動無効化保護

連続失敗の追跡

finlight はクォータを保護し、果てしない失敗試行を防ぐために、連続する webhook の失敗を追跡します。

仕組み:

  1. 成功でカウンターをリセット - 配信が成功するたび（HTTP 2xx）に失敗カウンターが 0 にリセットされます
  2. 失敗でカウンターを増加 - 配信が失敗するたびに連続失敗回数が増えます
  3. 10 回で自動無効化 - 10 回連続で失敗すると、webhook は自動的に無効化されます

自動無効化の挙動

自動無効化がトリガーされるとき:

  • すべての再試行を通じて 10 回連続の配信失敗
  • webhook のステータスが「有効」から「無効」に変わります
  • 自動無効化を示すダッシュボード通知が表示されます
  • 手動で再有効化するまでそれ以上の webhook 試行は行われません

重要な注意:

  • 自動無効化に数えられるのは連続した失敗のみです
  • 配信が 1 回でも成功すればカウンターは 0 にリセットされます
  • 手動での再有効化が必要です - webhook は自動的に有効化されません
  • すべての失敗タイプが数えられます（タイムアウト、4xx、5xx 応答）

例示シナリオ

シナリオ 1: カウンターのリセット

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

シナリオ 2: 自動無効化

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled
復旧オンラインに復帰

復旧と再有効化

手動での再有効化プロセス

再有効化の手順:

  1. 呼び出し履歴を使って根本原因を特定します
  2. エンドポイントの問題を修正します（認証、URL、サーバーエラー）
  3. ステータス設定を編集して webhook 詳細で webhook を再有効化します
  4. ダッシュボードのテストボタンで webhook を手動でテストします
  5. 最初の配信を監視して解決を確認します

予防策

自動無効化を避ける:

  • エンドポイントに適切なエラー処理を実装します
  • 適切な HTTP ステータスコードを返します
  • webhook の健全性を能動的に監視します
  • webhook の失敗に対してアラートを設定します
  • 本番の前に開発環境で変更をテストします
クォータ使用状況の追跡

クォータ管理

ダッシュボードのグラフで使用状況を確認できます。使用状況は遅延して記録される点にご注意ください。

失敗したリクエストもクォータに数えられる

重要: 失敗した配信を含め、すべての webhook 配信試行がサブスクリプションのクォータに数えられます。

数えられるもの:

  • 最初の配信試行 - クォータに数えられます
  • すべての再試行 - 各再試行が個別に数えられます
  • 失敗した配信 - それでもクォータを消費します
  • webhook のテストリクエスト - これもクォータに数えられます

クォータへの影響の例:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

クォータを効率的に管理する

ベストプラクティス:

  • エンドポイントの問題を素早く修正し、失敗した再試行を最小限に抑えます
  • 失敗パターンがないか呼び出し履歴を監視します
  • 本番で webhook を有効化する前に入念にテストします
  • 適切なステータスコードを返すために適切なエラー処理を使用します

クォータ保護: 自動無効化機能は、常に失敗するエンドポイントへの配信を停止することで、クォータの無駄遣いを防ぐのに役立ちます。

webhook 設定のガイダンスについては、webhook のメインドキュメントを参照してください。テストとデバッグについては、テストガイドを確認してください。