WebhookとAPI: プッシュ、ポーリング、それぞれの使いどころ

WebhookとAPIに関する一般的なアドバイスは不完全です。「リアルタイムの更新にはWebhookを使い、それ以外にはAPIを使う」というものです。それでは最も難しい部分が見落とされています。Webhookレシーバーは非同期メッセージコンシューマーであり、プッシュ配信を選択するということは、重複、通知の欠落、認証、リカバリに対する責任を受け入れることを意味します。有用な比較はプッシュとプルではありません。それは、どちらかのチャネルが失敗した場合に備えたリカバリパスを含めた、トラフィックの経済性 vs 運用の制御です。

目次

• WebhookとAPIをざっと比較
  • コマンドと通知を分離する
• 各パターンがデータをどう動かすか
  • Streamingは別の問題を解決する
• 設計すべき信頼性のトレードオフ
  • 各障害に保護策を合わせる
  • Acknowledgmentは耐久性の境界である
• Pollingがより安全な選択肢となる場合
  • Pollingに有利な制約を認識する
• メディアジョブのためのハイブリッドフローを構築する方法
  • タスクの永続的な所有権を確立する
  • 信頼できる完了に収束する
• ワークロードと制約で選択する
  • 総運用コストを決定打として使う

WebhookとAPIの比較

WebhookはHTTP API上に構築されたイベント配信メカニズムであり、APIの代替ではありません。 ほとんどのプロダクション環境での連携では、コマンドや信頼できる読み取りのためのリクエストパスと、変更通知のための通知パスの両方が必要です。

例えば、あなたのアプリケーションが動画生成ジョブを送信するとします。APIを使用する場合、あなたのバックエンドは保存されたタスク識別子を使ってGETリクエストを送信し、ジョブの現在のステータスを受け取ります。いつ要求するか、どのくらい待つか、リクエストが失敗した場合にどうするかは、あなたのアプリケーションが選択します。

Webhookを使用する場合、プロバイダーはあなたが登録したエンドポイントにジョブ完了イベントを送信します。あなたのバックエンドはその通知を受け入れ、完了したアセットの取得など、次のアクションをスケジュールします。元のブラウザセッションは接続を維持する必要はありません。

コマンドと通知を分離する

作業を送信することと、それが完了したことを知ることは、異なる操作です。APIは、基盤となる計算が完了するまで接続を開いたままにすることなく、タスクを即座に受け入れることができます。その後、Webhookが別途完了シグナルを提供します。

この区別により、一般的な設計ミス、つまりすべて非同期操作をオープン状態を維持しなければならないHTTPリクエストとして扱うことを防ぎます。また、その逆のミス、つまりイベント通知を現在の状態の完全な記録として使用しようとすることも防ぎます。

最初の決定事項: あなたのアプリケーションは、何かが変更されたときに反応する必要がありますか、それとも誰かが尋ねたときにのみ答えが必要ですか？

ユーザーがジョブ履歴画面を開いた場合、現在のレコードを取得します。完了したジョブが、誰もその画面を見ていない間にアセット配信をトリガーすべきであれば、イベント駆動パスを使用します。どちらのパターンもネットワーク障害の処理の必要性をなくすものではありませんが、それぞれ呼び出し側を異なる回復の立場に置きます。

各データ転送パターンの仕組み

ポーリングでは、クライアントは何も変更がなくても、タイマーに基づいてステータスリクエストを繰り返します。Webhookでは、プロバイダーはイベント発生後にリクエストを開始するため、通知トラフィックは時間ではなくアクティビティに追従します。

NylasのWebhookとポーリングの比較ガイドは、基盤となるトラフィックの例を示しています。1つのリソースを60秒ごとにポーリングすると、1日あたり1,440件のリクエストになります。一方、10,000アカウントの比較では、1日あたり2.88百万件のポーリングリクエストに対し、約500,000件のWebhook配信が発生します。

ポーリング間隔とイベント発生率によるトラフィックと遅延

ポーリングの平均値は、変更がポーリングスケジュールとは独立して発生すると仮定しています。これらは、プロバイダーが作業を実行する時間ではなく、次のチェックまでの待機時間を表しています。

間隔を短くすると、より多くのリクエストを消費することで発見時間が短縮されます。間隔を長くするとトラフィックは減少しますが、完了した作業が未発見のまま放置されます。アカウント規模では、控えめなスケジュールであっても、非アクティブなすべてのアカウントがチェックされるため、かなりのトラフィックが発生します。

Webhook配信は、その固定されたチェックスケジュールを排除しますが、配信数だけがインフラストラクチャのコストのすべてではありません。通知後のAPIルックアップ、配信の再試行、レシーバーのストレージ、ワーカーの実行も依然としてリソースを消費します。

これらは異なる通信パターンであり、互換性のあるラベルではありません。

ストリーミングは別の問題を解決します

ストリーミングテキスト応答は、リクエストを開いたままにし、tokenが生成され次第返します。対話型コーディングアシスタントの場合、個別の完了コールバックを受け取るよりも、最初のtokenまでの時間と出力の連続性が重要です。

当社のテキスト応答はtokenごとにストリーミングされますが、画像や動画のジョブは、準備ができたときにポーリングするか、Webhook通知を受け取るタスクを返します。メディアAPIドキュメントは、そのタスク指向のリクエストパスを実装するための出発点です。

ポーリング間隔を選択する前に、リソースごとのイベント発生率を見積もってください。静かなリソースと継続的に変化するリソースが自動的に同じスケジュールを共有すべきではありません。

ポーリングの場合、間隔を短くすると、より少ない検知遅延と引き換えにより多くのトラフィックが発生します。Webhookはその特定の交換を回避しますが、信頼性の高いレシーバーを運用するコストに置き換わります。

設計時に考慮すべき信頼性のトレードオフ

ウェブフックの配信は通常、少なくとも1回であり、厳密に1回ではありません。これは配信モデルを説明するものであり、プロバイダーが永遠にリトライすることを約束するものではありません。制限されたリトライでも未配信のイベントで終わる可能性があるため、ハッピーパスではなく最悪のケースを想定してレシーバーを設計してください。

タイムアウトは、ダウンストリームで何が起こったかを送信者に何も伝えません。レシーバーがイベントをストレージにコミットした後、ネットワーク上で確認応答を失う可能性があります。送信者がリトライすると、アプリケーションは同じイベントを再度受信するため、適切に処理する必要があります。

各障害に合わせた保護策

• 重複配信: 一意制約の下で安定したイベント識別子を保存します。プロバイダーがイベントと配信試行を区別する場合、試行IDではなくイベントIDによってビジネス処理を重複排除します。
• 繰り返される副作用: アセットの公開、アカウントの更新、顧客への通知を冪等にします。イングレスの重複排除は、アクションを実行した後、成功を記録する前にクラッシュするワーカーに対しては何の効果もありません。
• 順序不同のイベント: 遷移を適用する前に、信頼できる状態または文書化されたリソースバージョンを確認します。遅延した「処理中」イベントが完了したタスクを上書きしてはなりません。
• 処理の遅延: 高負荷な作業をキューワーカーに渡す前に、イベントを検証し、永続的に受け入れ、確認応答します。

プロバイダーのリトライポリシーは互換性がありません。Supabaseウェブフックドキュメント]では、20秒以内に2xx応答を要求し、指数関数的バックオフを使用し、5回の失敗した試行後に停止します。Svix配信保証ガイド]では、Dynamicの初回試行に加えて約1日間にわたる5回の再試行と、Gleanのステータス固有のリトライルールが記載されています。

プロバイダー別の文書化されたウェブフックリトライ動作

確認応答は耐久性の境界

永続ストレージへの保存前に成功を返すと、ロストウィンドウが発生します。送信者はリトライを停止しますが、アプリケーションには回復可能なものが何もありません。メディア処理が完了した後にのみ成功を返すと、逆の問題が発生します。不要なタイムアウトと重複配信です。完了したビジネス作業ではなく、永続的な受け入れを確認応答してください。

ペイロードを信頼する前に署名検証を行うべきです。署名スキームが必要とする場合は生のリクエストボディを保持し、再シリアル化されたオブジェクトに署名するのではなく、プロバイダーが文書化した検証手順に従ってください。

ワーカーのリトライが尽きた場合のデッドレター処理と、イベントID、タスクID、確認応答の失敗、処理結果を関連付ける配信オブザーバビリティを追加してください。同じワークフローのポーリング部分については、返されたステータスコードで障害を分類します。UberLLMのAPIは、402, 404, 429 および 503のようなエラーコード]で呼び出しを拒否します。これにより、調整ジョブは請求拒否をスロットリングや一時的に利用できない販売者から区別できます。

見逃されたポーリングは、再度確認することで回復されます。見逃されたウェブフックは、別の配信またはスケジュールに基づいて信頼できるタスクステータスを再読み込みする独立した調整パスを必要とします。レシーバーを公開するかどうかにかかわらず、そのパスを構築してください。それが「少なくとも1回」の配信を効果的な「厳密に1回」の処理に変えるものです。

ポーリングがより安全な選択肢である場合

Webhookは、単に高速なAPIであるだけでなく、配信の信頼性の問題でもあります。アプリケーションがレシーバー契約をサポートできない場合、ポーリングの方がより信頼性の高い選択肢となり得ます。

運用上の違いは、コンシューマーの境界で最も分かりやすくなります。

デスクトップエージェント、ファイアウォールの内側にある内部ツール、または一時的なCIランナーは、安定したインバウンドアドレスなしでアウトバウンドアクセスを持つ場合があります。これらのクライアントがコールバックを受信できるようにするには、追加のホスト型サービス、コンポーネント間の認証、および元の呼び出し元への永続的な引き渡しが必要になる場合があります。それはインフラであり、軽微な設定変更ではありません。

ポーリングが有利な制約を認識する

• 安定した公開エンドポイントがない場合： 一時的な開発環境を公開する代わりに、通信をアウトバウンドに保ちます。
• 永続的なイベントコンシューマーがない場合： 安全なストレージと処理を構築する間、信頼できるステータスをポーリングします。受信したイベントを忘れてしまうレシーバーは改善ではありません。
• コンシューマー制御のリカバリ： 独自の並行処理制限、メンテナンス期間、アプリケーションの期限に従ってチェックをスケジュールします。

開発者のラップトップ上のビルドツールがリモートメディアタスクを送信するとします。完了するまで定期的にチェックし、開発者がキャンセルした場合は停止し、保存されたタスク識別子から再開できます。アクティブなジョブの数が少ない場合、それは常に利用可能なレシーバーを維持するよりもシンプルで安価かもしれません。

ポーリングには規律が必要です。一時的な障害時にはバックオフし、すべてのクライアントのチェックを同期するのを避け、終了したタスクのチェックは停止します。アウトバウンドリクエストでもリトライストームが発生する可能性があります。

付属のビデオでは、リクエストとコールバックの違いを視覚化する別の方法が提供されています。

コンシューマーが確実にリカバリできるパターンを選択してください。最も高速な成功デモンストレーションができるパターンではありません。

インバウンドのWebhookトラフィックは、エンドポイントセキュリティ、署名チェック、キューイング、重複抑制、および可用性要件を追加します。ポーリングは、次の操作がいつ行われるかについて明示的な制御を提供しますが、プロバイダーのレート制限は引き続き適用されます。

インバウンド配信が実用的で、頻繁なイベントがそれを正当化する場合、ポーリングフォールバック付きのWebhookを使用してください。それ以外の場合は、独自のケイデンス、並行処理、およびタイムアウトでポーリングしてください。

メディアジョブ向けハイブリッドフローの構築方法

ハイブリッド統合では、コールバックを、作業が存在する唯一の証拠としてではなく、作業を確認するためのプロンプトとして扱います。永続化されたタスクIDは、開始リクエスト、受信通知、リカバリチェック、および最終的な顧客結果を接続します。

大量のメディアワークフローを円滑に進めるため、非同期タスクトラッキングとWebhookコールバックを使用します。画像や動画のジョブの場合、このトラッキングにより、ある販売者で中断が発生しても顧客のジョブが失われることはありません。

このワークフローは、送信、通知、およびステータスリカバリを分離して管理します。

タスクの永続的な所有権を確立する

1. API経由で送信し、返されたタスクIDを保存します。 ダウンストリーム作業を開始する前に、キューに入れられたステータスで永続化します。高速なコールバックが送信応答と競合する可能性があるため、可能な場合は事前にローカルの送信レコードを作成してください。よくある間違いは、コールバックが常にデータベースコミット後に到着すると仮定することです。一致しないイベントは、後で関連付けられるように保持します。

2. 受け入れられたイベントを永続的にキューに入れるレシーバーを登録します。 リクエストハンドラーは小さく保ち、安全に受け入れた後、速やかに確認応答します。ストレージへの保存前に成功を返したり、ハンドラー内で完了したアセットをダウンロードまたは変換したりしないでください。

3. 認証を検証し、処理の重複を排除します。 イベントが信頼または確認応答される前に、イングレスで署名検証が行われる必要があります。その後、ワーカーは効果を適用する前に永続化されたイベントIDを確認します。よくある間違いは、これらを処理後のオプションのクリーンアップとして扱うことです。中断されたワーカーが安全に再開できるように、受け入れステータスと処理ステータスを分離して管理します。

権威ある完了に収束する

4. タスクの権威あるステータスを取得します。 顧客ジョブを完了とマークする前に、保存されたタスクIDを使用します。イベントには識別子のみが含まれる場合があり、遅延通知は古い遷移を記述している可能性があります。画像編集の実装については、写真編集APIガイド]が具体的なリクエストワークフローを提供しており、それを基に構築できます。

5. 期待される期間を超えて保留中のタスクをポーリングします。 各チェックサイクルで、バックオフ、ジッター、および最大試行回数を使用します。コールバックがない場合に、元のタスクがすでに完了している可能性があるため、生成を盲目的に再送信しないでください。

6. アプリケーションの期限を設定し、古いタスクを毎日調整します。 生成失敗とステータスチェック失敗を区別します。期限までにプロバイダーの状態が不明な場合は、顧客インターフェースを無期限にキューに入れたままにするのではなく、明示的なリカバリまたは失敗の結果を記録してください。

ヘルスチェック： 保存されたすべてのタスクIDは、タイムアウト内に、完了または失敗のいずれかの最終的なアプリケーション結果につながる必要があります。未解決のプロバイダーの状態をオペレーターに可視化し、アプリケーションのタイムアウトによってリカバリが必要な結果が放棄されないようにしてください。

ワークロードと制約で選択する

まずワークロードから始め、デプロイがサポートできないパターンは除外してください。受信クライアントがインバウンドリクエストを受け入れられない場合や、チームが中断された処理を回復できない場合、最速の通知メカニズムも役に立ちません。

ワークロードとパターンのマッピング

ブラウザは自身のバックエンドを介してアプリケーションの更新を受け取ることができますが、そのバックエンドがwebhookレシーバーを所有します。その責任を回避するために、プロバイダーの認証情報やコールバック検証シークレットをブラウザに入れないでください。

ワークロードとデプロイの制約は一緒に評価されるべきです。

総運用コストを決定打として使用する

Xictronのwebhookアーキテクチャ記事で引用された分析によると、30百万回のポーリングリクエストのうち1.5%のみが更新を返しました。これは、調整が不十分なポーリングがいかにトラフィックを無駄にするかを示しており、すべてのwebhook統合が安価になるわけではありません。

ポーリング間隔、イベント頻度、ペイロードサイズ、プロバイダーの制限を、レシーバーホスティング、キューのストレージ、監視、インシデント対応と比較してください。また、webhookワーカーが依然として必要とするAPI読み取り回数も数えてください。軽量な通知の後に権威あるフェッチを行うことは、リクエスト不要のアーキテクチャではありません。

マルチプロバイダーアプリケーションの場合、イベントスキーマの一貫性とフォールバック動作を検査してください。タスクステータスを独自のアプリケーションモデルに正規化することは、通知速度のわずかな違いよりも重要になる場合があります。

選択ルール: ユーザーが求める要件を満たす最もシンプルな主要パスを優先し、レイテンシを最適化する前にリカバリパスに資金を投入してください。

アプリケーションがリクエストへの応答を必要とする場合はAPIを使用してください。変更に反応する必要があり、安全で耐久性のあるレシーバーを運用できる場合はwebhookを使用してください。長時間実行されるジョブには独立したステータスチェックを追加し、インバウンド配信が不可能な場合はポーリングをコンシューマー制御のままにしてください。

実装の前に、リソースごとの予想イベントレート、安定したendpointを公開できるかどうか、重複処理をどのように扱うかを書き出してください。その後、シンプルなAPIリクエストを行い、コールバックを追加する前に結果のタスクを保存および取得できることを確認してください。

---

UberLLMは、すべてのモデルを1つのAPI keyで提供し、OpenAIおよびAnthropicのワイヤーフォーマットを受け入れるため、既存のクライアントは適切なbase URLと認証情報を使用できます。画像および動画のワークフローでは、結果の準備ができたときにタスクポーリングまたはwebhook通知を選択してください。UberLLMにアクセスしてリクエストパスをテストし、その後、アプリケーションが必要とする完了パスとリカバリパスを追加してください。