GoogleがGemini APIにWebhookを追加した。2026年5月4日の公式アナウンスにより、開発者はバッチ処理・動画生成・非同期タスクの完了を即座に受け取れるようになった。
この記事でわかること：
- Webhookがなぜ今のGemini APIに必要だったか
- 静的Webhookと動的Webhookの使い分け
- 対応しているイベントの種類
- セキュリティ設計と実装時の注意点
ポーリングが開発コストを押し上げていた
GeminiのDeep Research、長尺動画生成、バッチAPIといった機能は、処理が完了するまで数分から数時間かかる。これまで開発者はGETリクエストを一定間隔で繰り返し送り、ジョブのステータスを確認するポーリングに頼っていた。
タスクが1本なら許容範囲だが、数千件の並列処理になると状況が変わる。常時タイマーを動かし、状態管理ロジックを書き、リトライ処理を組む。この作業コストが積み重なり、APIクォータの消費量も無視できない量になる。
タスク完了を即時プッシュする仕組み
Webhookはこの構造を逆転させる。タスクが完了した瞬間、Gemini APIがあなたのサーバーにHTTP POSTを送る。クライアント側はエンドポイントを用意して待つだけでよく、タイマーや状態管理のコードは不要になる。
ペイロードは「薄い設計」を意図的に採用している。動画ファイルや大量のバッチ出力をそのまま送るのではなく、タスクID・ステータス・結果ファイルへのポインタ（output_file_uriなど）を渡す。リトライ時の帯域コストを抑え、権限管理もシンプルに保つためだ。
配信は「少なくとも1回」を保証し、失敗時は最大24時間の自動リトライが行われる。
静的と動的、2種類の設定方法
設定方法は2通り用意されている。
静的Webhookはプロジェクト全体に適用するグローバル設定だ。WebhookService APIで一度登録すれば、そのプロジェクト内のすべての対象イベントに反応する。すべてのバッチ完了をSlackチャンネルに流す、動画生成のたびにCMSと同期するといった用途に向いている。署名はHMAC対称鍵で行われる。シークレットはAPI作成時に一度だけ返却されるため、即座に安全なストレージに保存する必要がある。
動的Webhookはリクエストごとに宛先URLを指定する方式だ。タスク送信時にwebhook_configフィールドへURLを渡すと、そのタスクの完了通知だけが指定のエンドポイントへ届く。マルチテナントのSaaSで顧客ごとにコールバック先を分けるケースに適している。署名にはJWKS（RS256公開鍵）を使い、対称鍵の管理が不要になる。user_metadataフィールドで任意のキーバリューを付与でき、タスクとビジネスコンテキストのマッピングテーブルを省ける設計になっている。
対応しているイベントの種類
現時点でWebhookが通知するイベントは3グループある。
Batch API関連はbatch.succeeded（成功）・batch.failed（失敗）・batch.cancelled（キャンセル）・batch.expired（TTL超過）の4種類。動画生成はvideo.generatedのみで、長尺動画が完成した時点でファイルIDと動画URIが届く。
Interactions API関連はinteraction.requires_action（ツール呼び出しへの応答が必要）・interaction.completed（マルチターン完了）・interaction.failed・interaction.cancelledの4種類。
すべてのペイロードは{ "type": "batch.succeeded", "data": { ... } }という統一フォーマットで届く。typeフィールドによるルーティングで複数のパイプラインに振り分けられるため、受信側の実装も単純に保てる。
セキュリティ設計
Webhookの実装はStandard Webhooks仕様に準拠している。StripeやResendなど他サービスのWebhook統合を経験していれば、ほぼ同じ要領で扱える。
通知リクエストにはwebhook-signature・webhook-id・webhook-timestampの3ヘッダーが付く。タイムスタンプが5分を超えたリクエストを拒否することがリプレイ攻撃への基本的な対策となる。webhook-idを使った重複排除も合わせて実装しておくとさらに安全性が上がる。
受信側のエンドポイントは数秒以内に2xxを返すこと。データベースへの書き込みや下流APIへの呼び出しは非同期キューに渡す設計が推奨されている。
今すぐ利用できる
この機能はすべてのGemini API利用者が使える状態になっている。
公式ドキュメントとGitHub上のCookbookに、静的Webhookのエンドポイント登録からシグネチャ検証までのサンプルコードが一通りそろっている。バッチ処理や動画生成の非同期ワークフローを抱えているチームにとって、ポーリング構成を見直す具体的な理由が生まれた。