［開発者向け］Gemini APIにWebhook機能が登場——長時間ジョブのポーリングが不要に

2026-05-05

はじめに

　GoogleはGemini APIに、長時間ジョブの完了をリアルタイムで通知するWebhook機能を追加しました。2026年5月4日にGoogleが公式ブログで発表したもので、バッチ処理や動画生成など時間のかかる処理で従来必要だったポーリング操作が不要になります。

参考記事

タイトル: Reduce friction and latency for long-running jobs with Webhooks in Gemini API
著者: Lucia Loher / Hussein Hassan Harrirou
発行元: Google Blog
発行日: 2026年5月4日
URL: https://blog.google/innovation-and-ai/technology/developers-tools/event-driven-webhooks/

要点

Gemini APIにWebhook機能が追加され、長時間ジョブの完了時にHTTP POSTでサーバーへリアルタイム通知が届くようになった
Deep Researchや長尺動画生成、Batch APIなど数分〜数時間かかる処理において、従来のポーリング（定期的なGETリクエストによる完了確認）が不要になった
Standard Webhooks仕様に準拠し、署名ヘッダーによる認証・リプレイ攻撃対策・最大24時間の自動リトライが実装されている
Webhookはプロジェクトレベル（HMAC認証）またはリクエスト単位（JWKS）で設定でき、Python SDKからwebhook_configパラメータを渡すだけで利用できる

詳細解説

なぜWebhookが必要か——ポーリングの限界

　Googleの発表によれば、Gemini APIがエージェント型ワークフローや高ボリューム処理への対応を進める中で、Deep Researchや長尺動画の生成、Batch APIを通じた大量プロンプト処理など、完了まで数分〜数時間かかるオペレーションが増えています。

　これまで開発者はジョブの完了確認に「ポーリング」——GETリクエストを繰り返し送り続けて状態を確認する方式——に頼っていました。この方法はサーバーリソースを無駄に消費するだけでなく、実装の複雑さにもつながります。Webhookはその逆で、ジョブが完了した瞬間にGemini APIのサーバー側からHTTP POSTを送る「プッシュ型」の通知方式です。ポーリングのような待機ループを自前で書く必要がなくなり、アーキテクチャをシンプルに保てると考えられます。

セキュリティと信頼性の設計

　今回のWebhook実装はStandard Webhooks仕様に厳密に準拠しています。Standard WebhooksはWebhookの相互運用性とセキュリティを標準化するオープン仕様で、エコシステム全体での互換性を意識した実装です。

　すべてのリクエストにはwebhook-signature、webhook-id、webhook-timestampの3つのヘッダーが付与されます。これにより、冪等性（べきとうせい：同一リクエストを複数回処理しても結果が変わらない性質）が確保されるほか、過去の正規リクエストを再送する「リプレイ攻撃」を防ぐことができます。また、Googleは「at-least-once（最低1回）」の配信を保証しており、通知が失敗した場合は最大24時間にわたって自動リトライが行われます。

　本番環境でのWebhook運用においては、受信側のサーバーで署名検証を実装したうえで、同じ完了通知を複数回受け取っても処理が重複しないよう冪等性を確保する設計が重要だと考えられます。

設定方法と実装例

　Webhookの設定方法は2種類あります。

プロジェクトレベルのグローバル設定: HMAC（ハッシュベースのメッセージ認証コード）によって認証し、プロジェクト配下のすべてのジョブに共通のエンドポイントを設定します。
リクエスト単位の動的設定: JWKS（JSON Web Key Set：公開鍵の集合を表すJSON形式）を使い、ジョブごとに異なるエンドポイントへルーティングできます。

　以下は、Batch APIのジョブ作成時にWebhookを動的に指定するPython SDKのサンプルコードです（参考記事のサンプルをもとにしています）。

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}")

　webhook_configのurisに通知先のエンドポイントURLをリストで指定します。user_metadataにはジョブを識別するための任意のキーバリューを渡すことができ、受信側でジョブの種別や優先度を判断するのに活用できます。バッチジョブが完了すると、指定したエンドポイントにHTTP POSTリクエストが送信されます。

利用開始の方法

　この機能はGemini APIを利用するすべての開発者に対してすでに提供されています。Googleは以下のリソースを案内しています。

公式ドキュメント: Webhooks documentationでイベントカタログの全体像とエンドポイントのセキュリティ設定方法を確認できます。
ハンズオンCookbook: Google Gemini Cookbook（GitHub）では、エンドツーエンドの実装をJupyterノートブックで実際に試すことができます。

まとめ

　Gemini API Webhookは、長時間の非同期処理を扱う開発者にとって実用的なアップデートだと思います。Standard Webhooks準拠のセキュアな設計と24時間の自動リトライ保証は、本番運用に耐えうる信頼性があると考えられます。Gemini APIのエージェント機能を使っている方は、ポーリングからの切り替えを検討する価値がある機能だと思います。