Gemini API、イベント駆動 Webhook を提供

Gemini API は、Deep Research や長時間の動画生成、Batch API による大量プロンプト処理のように数分から数時間かかる非同期ジョブ向けに、イベント駆動 Webhook を提供する。完了を GET で繰り返し確認するポーリングを排し、タスク完了時にサーバーへ HTTP POST を送る。

主な仕様は次のとおり。

• プロジェクト全体の静的 Webhook（HMAC 署名）と、リクエスト単位で URL を上書きする動的 Webhook（JWKS 署名）の二方式
• Standard Webhooks 仕様に準拠し、webhook-signature、webhook-id、webhook-timestamp ヘッダーで署名・べき等性・リプレイ攻撃対策
• 少なくとも一度は届く配信保証と、失敗時は最大24時間の自動再試行
• 通知対象は Batch ジョブ、Interactions API、動画生成など。ペイロードは結果本体ではなく ID や出力 URI などの薄いスナップショット

動的 Webhook は webhook_config を指定した非同期リクエストで使う。Python SDK の例は次のとおり。

response = client.interactions.create(
    model="gemini-3.5-flash",
    input="Tell me a short joke about programming.",
    background=True,
    webhook_config={
        "uris": ["https://my-api.com/gemini-webhook-dynamic"],
        "user_metadata": {"job_group": "nightly-eval", "priority": "high"},
    },
)

受信側は数秒以内に 2xx を返す必要がある。すべての Gemini API 利用者が利用可能。