Gemini API の Webhooks で長時間実行ジョブの摩擦と遅延を削減
Google は Gemini API にイベント駆動型の Webhooks を導入し、長期実行タスクにおけるポーリングの非効率性を解消して、エージェントワークフローの実用性を大幅に向上させた。
キーポイント
ポーリング不要なリアルタイム通知の実装
Gemini API がタスク完了時に HTTP POST をプッシュする仕組みを導入し、Deep Research やバッチ処理など長時間かかるジョブの待機時間を解消した。
堅牢なセキュリティと信頼性の保証
Webhook 署名（signature, id, timestamp）によるリプレイ攻撃防止、24 時間以内の自動再試行による「少なくとも 1 回」の配信保証を実装している。
柔軟な設定と多層的な認証
プロジェクトレベルでの HMAC によるグローバル設定に加え、リクエスト単位で JWKS を使用した動的な Webhook ルーティングが可能になった。
影響分析・編集コメントを表示
影響分析
この機能は、LLM を活用した複雑なエージェントアプリケーションや大規模バッチ処理の開発において、リソース効率とレスポンスタイムを劇的に改善する。開発者がポーリングロジックに費やす時間を削減し、より信頼性の高い非同期ワークフローの構築が可能になることで、Gemini の実用範囲が拡大する。
編集コメント
長時間処理を要する AI アプリケーション開発における最大のボトルネックの一つである「ポーリングの非効率性」を解消する重要なアップデートです。セキュリティと信頼性を両立した設計は、本番環境での採用を後押しするでしょう。
本日、Gemini API を用いて複雑で長時間実行されるエージェント型アプリケーションを構築する際、より容易かつ効率的になるよう取り組みを行いました。私たちは、非効率なポーリングの必要性を排除するプッシュ型の通知システムであるイベント駆動 Webhooks を導入します。
Gemini が Deep Research や長編動画生成、Batch API を通じて数千ものプロンプトを処理するなど、エージェント型ワークフローや高ボリューム処理へと移行するにつれ、操作には数分乃至数時間かかることもあります。これまで開発者は、ジョブが完了したかを確認するために継続的なポーリング（例：GET 操作の繰り返し呼び出し）に頼る必要がありました。
今後は、Gemini API はタスクが完了した瞬間に、リアルタイムの HTTP POST ペイロードを直接サーバーへプッシュできるようになります。
この機能は信頼性とセキュリティを念頭に構築されました。実装は「Webhooks 仕様」に厳密に従っており、すべてのリクエストは webhook-signature、webhook-id、webhook-timestamp ヘッダーを使用して署名され、冪等性が保証されるとともにリプレイ攻撃が防止されます。また、最大 24 時間にわたる自動再試行により、「少なくとも 1 回」の配信を保証します。
Webhooks はプロジェクトレベルでグローバルに設定可能（HMAC によって保護）であり、特定のジョブをルーティングするために個別のリクエスト単位で動的に上書きすることも可能です（JWKS によって保護）。
Python SDK を使用してバッチタスクに対して Webhook を動的に構成する簡単な例を示します：
python
from google import genai
from google.genai import types
client = genai.Client()
file_batch_job = client.batches.create(
model="gemini-3-flash-preview",
src=inline_requests,
config={
"display_name": "My Setup",
"webhook_config": {
"uris": ["https://my-api.com/gemini-webhook-dynamic"],
"user_metadata": {"job_group": "nightly-eval", "priority": "high"},
},
},
)
print(f"Created batch job: {file_batch_job.name}")
この機能は、Gemini API を利用するすべての開発者に対して現在利用可能です:
- ガイドを読む：イベントカタログ全体を確認し、エンドポイントをどのように保護するかを学ぶには、こちらをご覧ください。
- ハンズオン演習：Webhook を使用したエンドツーエンドの統合を構築するための包括的なガイドを用意しました。
原文を表示
Today, we're making it easier and more efficient to build complex, long-running agentic applications with the Gemini API. We are introducing event-driven Webhooks, a push-based notification system that eliminates the need for inefficient polling.
As Gemini shifts toward agentic workflows and high-volume processing — like Deep Research, long video generation, or processing thousands of prompts via the Batch API — operations can take minutes or even hours. Until now, developers had to rely on continuous polling (e.g., repeatedly calling GET operations) to check if a job was completed.
Now, the Gemini API can simply push a real-time HTTP POST payload to your server the instant a task finishes.
We’ve built this with reliability and security in mind. Our implementation strictly adheres to the
specification. Every request is signed using webhook-signature, webhook-id, and webhook-timestamp headers, ensuring idempotency and preventing replay attacks. We also guarantee "at-least-once" delivery with automatic retries for up to 24 hours.
You can configure webhooks globally at the project level (secured via HMAC), or override them dynamically on a per-request basis to route specific jobs (secured via JWKS).
Here's a quick example of how you can dynamically configure a webhook for a batch task using the Python SDK:
python
from google import genai
from google.genai import types
client = genai.Client()
file_batch_job = client.batches.create(
model="gemini-3-flash-preview",
src=inline_requests,
config={
"display_name": "My Setup",
"webhook_config": {
"uris": ["https://my-api.com/gemini-webhook-dynamic"],
"user_metadata": {"job_group": "nightly-eval", "priority": "high"},
},
},
)
print(f"Created batch job: {file_batch_job.name}")This feature is available now for all developers using the Gemini API:
- Read the guide: Check out the to explore the full event catalog and learn how to secure your endpoints.
- Hands-on practice: We've prepared a comprehensive to help you build an end-to-end integration with webhooks.
関連記事
今日のまとめ
AI日報で今日の重要ニュースをまとめ読み