Webhook

Webhook を使用すると、非同期オペレーションまたは長時間実行オペレーション（LRO）が完了したときに、Gemini API がリアルタイム通知をサーバーにプッシュできます。これにより、ステータスの更新について API をポーリングする必要がなくなり、レイテンシとオーバーヘッドが削減されます。

Webhook は、Batch ジョブ、インタラクション、動画生成などのオペレーションで使用できます。

仕組み

ジョブが完了したかどうかを確認するために GET /operations を繰り返しポーリングする代わりに、イベントトリガーが発生するとすぐにリスナー URL に HTTP POST リクエストを送信するように Gemini API Webhook を構成できます。

Gemini API では、Webhook を構成する次の 2 つの方法がサポートされています。

静的 Webhook: Gemini WebhookService API で構成されたプロジェクトレベルのエンドポイント。グローバルな統合（Slack への通知、データベースの同期など）に適しています。
動的 Webhook: 特定のジョブ呼び出しの構成ペイロードで Webhook URL を渡すリクエストレベルのオーバーライド。特定のジョブを専用のエンドポイントにルーティングする場合に最適です。

静的 Webhook はプロジェクト全体に登録され、一致するイベントが発生するとトリガーされます。

エンドポイントは、SDK または REST API を使用して作成できます。

重要: ウェブフックを作成すると、API は署名シークレットを 1 回だけ返します。署名を後で検証するために、これを安全に保存する必要があります（環境変数など）。署名シークレットを紛失した場合は、ローテーションする必要があります。

from google import genai

client = genai.Client()

webhook = client.webhooks.create(
    name="MyBatchWebhook",