GoogleのGemini APIに、長時間実行ジョブ向けのWebhook機能が追加された。Deep Research、長尺動画生成、大規模バッチ処理といった分〜時間単位で走るAIジョブの完了通知を、ポーリング不要でリアルタイムに受け取れるようになる。これは単なるAPIの利便性向上にとどまらず、エージェント型アプリケーションのアーキテクチャ設計に直接影響する重要なアップデートだ。

ポーリングの何が問題だったのか

従来、Gemini APIで長時間ジョブを扱う場合、開発者は定期的にGETリクエストを送り続けて完了状態を確認するポーリング方式を使うしかなかった。これには明確なコストがある。

  • サーバー負荷と無駄なネットワーク通信: ジョブが終わっていないのにAPIを叩き続ける
  • レイテンシ: ポーリング間隔によっては、完了からの通知までタイムラグが生まれる
  • コードの複雑さ: 状態管理、タイムアウト処理、バックオフロジックなどを自前で実装する必要がある

Webhook方式で何が変わるか

Webhookを使えば、AIサービス側がジョブ完了の瞬間にHTTP POSTリクエストを開発者のエンドポイントに送りつけてくる。いわゆる「プッシュ型」の通知だ。

セキュリティ設計もきちんとしており、Standard Webhooks仕様に準拠。webhook-signature、webhook-id、webhook-timestamp の3ヘッダーで署名検証が行われ、リプレイアタック対策と冪等性が担保される。配信保証は「at-least-once（少なくとも1回）」で、最大24時間の自動リトライが行われる。

設定方法は2種類ある。

  • プロジェクトレベル: HMACで保護されたグローバル設定。すべてのジョブに同じエンドポイントを使う場合に適している
  • リクエストレベル: JWKSで保護された動的設定。ジョブごとに異なるエンドポイントに振り分けたい場合に使う

実務への影響

この変更が最も効くのは、バッチAPIを使って大量のプロンプトを一括処理するケースだ。数千件のプロンプト処理、長尺動画の生成、Deep Research機能など、分〜時間単位で走るジョブに対してポーリングを書かずに済む。

Azureを使っているシステムを設計している読者にとっては、Azure Event GridやService BusのWebhookサブスクリプションと同じ発想だと理解すると馴染みやすい。Azure Functionsをトリガーとして受け口に使えば、外部AIサービスのWebhookとAzureのサーバーレス処理を組み合わせたパイプラインも比較的容易に構築できる。

実装の際に押さえておきたいポイント：

  • 署名検証を必ず実装する: webhook-signatureヘッダーの検証をサボると、なりすましリクエストを処理するリスクがある
  • 冪等な処理を設計する: at-least-once保証なので、同じWebhookが複数回届く可能性がある。webhook-idを使って重複排除のロジックを入れること
  • エンドポイントの応答を素早く返す: Webhook受信後の処理は非同期にし、まず200を即返す設計にする。重い処理を同期で実行すると再送ループに巻き込まれる

筆者の見解

今回のWebhook対応は、技術的には特別目新しいものではない。イベント駆動アーキテクチャは長年Webエンジニアが使い続けてきた標準的なパターンだ。しかし、AIサービスがこのパターンを正式サポートし始めたという点に意味がある。

エージェント型AIアプリケーションが普及するにつれ、「リクエスト→即レスポンス」という同期モデルの限界はどのプラットフォームでも顕在化してくる。複数のAIジョブをオーケストレーションし、その結果に応じて次のアクションを決める——そういう自律的なワークフローを作ろうとすると、ポーリング前提の設計はすぐに破綻する。

この動きは、AIサービスが「呼べば答えるツール」から「自律的に動くエージェントのインフラ」へと移行していることの表れだと読んでいる。「副操縦士」的な確認待ちの設計ではなく、完了を検知してそのまま次のステップを自律実行する——そのためのインフラとして、Webhookは本質的に正しい方向性だ。

開発者として今確認しておくべきは、使っているAIサービスがイベント駆動をどこまでサポートしているかだ。どのサービスを使っていても、自律エージェントの設計でポーリング依存のアーキテクチャは早晩置き換えが必要になる。その設計転換を今のうちに意識しておくことが、エージェント時代に向けた準備になる。

出典: この記事は Reduce friction and latency for long-running jobs with Webhooks in Gemini API の内容をもとに、筆者の見解を加えて独自に執筆したものです。