2026 年 5 月 4 日，Google 在官方博客正式宣佈: Event-driven webhooks are now available in Gemini API。兩天後的 5 月 6 日上午 10 點（北京時間），這封來自 Google AI Studio 的郵件抵達全球開發者的收件箱，標誌着 Gemini API webhooks 已經對所有用戶全量開放。
對很多在做 Deep Research、長視頻生成或大規模 Batch 推理的團隊來說，這是一個真正意義上的"基礎設施級"更新——它不是新模型、也不是新參數，但它直接重寫了"如何與一個長時間運行的 AI 任務對話"的方式。
本文基於 Google 官方博客和 Gemini Cookbook 的一手資料，系統拆解 Gemini API webhooks 的事件類型、兩種配置方式、簽名驗籤機制和上手代碼，同時討論它對國內開發者意味着什麼。
Gemini API webhooks 是什麼: 一句話理解事件驅動 Webhook
Gemini API webhooks 本質上是一套基於 HTTP POST 的事件推送機制。當你提交的 Batch 任務、視頻生成任務或 Interactions 異步對話完成時，Gemini API 會主動把一條帶簽名的 JSON 通知推送到你預先註冊的服務器地址，而不是要求你不斷地用 GET 請求去輪詢任務狀態。
這種"反向調用"的設計在傳統軟件開發中並不新鮮，但放在 AI 推理場景下意義重大。Gemini 當前主推的 Deep Research、Veo 長視頻生成和 Batch API 單任務時長動輒數分鐘到數小時，如果繼續走輪詢路徑，客戶端要維持長連接、定時器、錯誤恢復邏輯，運維成本和 API 配額浪費都會成倍上升。
🎯 快速理解: Gemini API webhooks = 把"我做完了"這件事，從客戶端反覆問，變成服務端主動告訴你。開發者只需要寫好一個回調端點，然後等通知。國內團隊如果通過 API易 apiyi.com 這類中轉通道接入 Gemini，同樣可以利用 webhook 通知減少國際鏈路上的輪詢請求，顯著降低延遲和帶寬消耗。
需要注意，Gemini API webhooks 推送的是"薄載荷"（thin payload）——它告訴你任務的 ID、狀態和結果文件的訪問指針（例如 output_file_uri），而不會直接把幾十 MB 的視頻或上萬行 batch 輸出塞進 POST body。這是一種刻意爲之的設計，既減小了重試時的數據成本，也讓權限控制更清晰。
爲什麼 Gemini API webhooks 終結了"輪詢時代"
理解 Gemini API webhooks 的價值，要先理解輪詢的代價。在 webhook 上線之前，一個典型的 Batch 任務流程長這樣: 提交任務 → 拿到 operation ID → 用 setInterval 每 30 秒 GET 一次 → 在狀態變成 SUCCEEDED 之前不能下班。這套流程對單任務尚可，但放到生產環境會迅速變形。
下表對比了輪詢模式和事件驅動 Webhook 模式在多個維度上的差異，這也是 Google 在官方博客中重點強調的遷移收益點。
| 對比維度 | 傳統輪詢模式 | Gemini API 事件驅動 Webhook |
|---|---|---|
| 通知延遲 | 取決於輪詢間隔（常見 10-60 秒） | 毫秒級（任務一結束即推送） |
| API 配額消耗 | 每次輪詢都計入讀配額 | 推送由 Google 側發起，不消耗調用方配額 |
| 客戶端複雜度 | 需要定時器、狀態機、錯誤重試 | 只需一個 HTTP POST 端點 + 簽名校驗 |
| 大規模併發 | 數千任務時輪詢風暴明顯 | 推送獨立到達，易於橫向擴展 |
| 失敗恢復 | 客戶端需自行實現 | 服務端自動指數退避重試，最長 24 小時 |
| 適合場景 | 短任務、低併發 | 長任務、高併發、agentic 流水線 |
從這張表可以看出，Gemini API webhooks 不僅僅是"省點輪詢代碼"，它實際上把"任務編排"這件事的責任邊界，從客戶端往服務端推了一大步。對於跑 agentic workflow 的團隊來說，Webhook 加上 Cloud Run、Cloud Functions 或國內 Serverless 服務，基本可以做到全異步、零長連接。
💡 從輪詢遷移: 如果你現有的代碼是圍繞 GET /operations 寫的，遷移到 webhook 模式只需把"輪詢循環"替換爲"事件回調路由"，業務邏輯幾乎可以零改動。國內團隊通過 API易 apiyi.com 接入 Gemini API 時，可以讓 webhook 端點直接對接自家內網，既保留事件驅動的優勢，又規避跨境長連接的不穩定。
Gemini API webhooks 的兩種配置方式: Static vs Dynamic
Gemini API webhooks 支持兩種註冊方式，分別面向"全局通知"和"按任務路由"兩種典型需求。理解這兩者的區別，直接決定了你後續的密鑰管理和驗籤策略。
Static Webhook: 項目級全局事件訂閱
Static Webhook 通過 WebhookService API 註冊一次，對該項目下所有匹配事件生效。它適合"無論哪個任務完成都要廣播"的場景，例如把所有 batch.succeeded 事件轉發到團隊 Slack、把所有 video.generated 同步到自家 CMS 或對象存儲。
簽名機制上，Static Webhook 使用 HMAC 對稱密鑰。Google 在創建時返回一個 signing secret，而且只返回一次——必須立刻保存到密鑰管理服務，否則只能刪除並重建。
Dynamic Webhook: 請求級精細路由
Dynamic Webhook 是更"細顆粒度"的方式: 你在每次提交任務的時候，在 webhook_config 字段裏臨時指定一個 URL，Google 就會把這一個任務的事件推送到那個地址。它特別適合多租戶 SaaS 場景——不同客戶的任務推到不同回調端點，業務隔離非常清晰。
Dynamic Webhook 還允許在配置裏攜帶 user_metadata 字段（任意鍵值對，如 {"job_group": "nightly-eval"}），Google 會在推送時原樣回傳。這是一個非常實用的設計，讓你不用維護一張額外的"任務 → 業務上下文"映射表。
簽名機制上，Dynamic Webhook 使用 JWKS 異步公鑰（RS256），公鑰地址爲 generativelanguage.googleapis.com/.well-known/jwks.json，你的服務在校驗時只需取公鑰即可，不需要保管對稱密鑰。
| 維度 | Static Webhook | Dynamic Webhook |
|---|---|---|
| 註冊方式 | 通過 WebhookService API 一次性註冊 | 每個任務請求中臨時指定 |
| 作用範圍 | 整個項目 | 單個任務 |
| 簽名算法 | HMAC 對稱密鑰 | JWKS / RS256 公鑰 |
| 密鑰管理 | 創建時返回一次，需自行保存 | 無需管理對稱密鑰，從公鑰端點拉取 |
| user_metadata | 不支持 | 支持任意鍵值對透傳 |
| 典型場景 | 全局通知、Slack 集成、統一歸檔 | 多租戶路由、按任務分發結果 |
| 推薦人羣 | 團隊內部統一管線 | SaaS 平臺、對外開放服務 |
🎯 選擇建議: 單團隊內部統一處理，優先選 Static Webhook；面向客戶開放、需要按租戶路由的，優先 Dynamic Webhook。如果通過 API易 apiyi.com 中轉 Gemini API，兩種模式都可以原生使用，簽名頭部和事件 payload 與官方完全一致，遷移沒有額外門檻。
Gemini API webhooks 上手教程: 5 行代碼完成訂閱
下面給出一份極簡的上手代碼，從創建靜態 webhook 到驗籤接收事件，目標是讓你在 10 分鐘內跑通一個最小可用閉環。
用 Python SDK 創建一個 Gemini API 事件驅動 Webhook
from google import genai
import os
client = genai.Client（）
webhook = client.webhooks.create（
subscribed_events=["batch.succeeded"， "video.generated"]，
name="prod_global_notify"，
uri="https://your-server.example.com/gemini/webhook"，
）
# signing_secret 只返回一次，務必立刻持久化
os.environ["WEBHOOK_SIGNING_SECRET"] = webhook.new_signing_secret
這段代碼做了兩件事: 一是註冊了一個監聽 batch 完成和視頻生成完成兩類事件的全局端點；二是把 Google 返回的簽名密鑰存進環境變量。生產環境強烈建議把 secret 寫入 Secret Manager、Vault 或類似服務，而不是落到代碼倉庫或日誌裏。
用 Node.js + Express 接收並驗籤
import express from "express"；
import { Webhook } from "standardwebhooks"；
const app = express（）；
const wh = new Webhook（process.env.WEBHOOK_SIGNING_SECRET）；
app.post（"/gemini/webhook"， express.raw（{ type: "*/*" }）， （req， res） => {
try {
const event = wh.verify（req.body， req.headers）；
console.log（"event:"， event.type， "data:"， event.data）；
res.status（200）.send（"ok"）；
} catch （e） {
res.status（400）.send（"invalid signature"）；
}
}）；
app.listen（8080）；
注意幾個關鍵點: 一定要用 express.raw 拿到原始字節流來驗籤，否則 JSON 解析會破壞簽名；返回 2xx 必須在幾秒內完成，任何重邏輯（寫庫、調下游）都應該異步丟到隊列裏；timestamp 超過 5 分鐘的請求建議直接拒絕，這是 Standard Webhooks 推薦的 replay 防禦實踐。
🚀 實戰提示: 如果你的服務部署在國內，而 Webhook 端點需要被 Google 直接訪問，建議把端點暴露在境外節點或 CDN 邊緣節點，然後再回源到內網。或者使用 API易 apiyi.com 這類同時支持 Gemini API 調用和回調代理的中轉服務，把 webhook 推送先收到中轉層，再由中轉層轉發到內網，可以省掉一層 NAT 和 SSL 複雜度。
Gemini API webhooks 支持的事件類型一覽
目前 Gemini API webhooks 主要覆蓋三大類長任務的狀態變化事件，每一類都對應一組結果指針字段。下表整理了官方 Cookbook 中明確給出的事件清單。
| 事件分組 | 事件名稱 | 觸發時機 | 關鍵 payload 字段 |
|---|---|---|---|
| Batch API | batch.succeeded | 批處理任務全部成功 | id、output_file_uri |
| Batch API | batch.failed | 批處理任務失敗 | id、error |
| Batch API | batch.cancelled | 用戶主動取消 | id |
| Batch API | batch.expired | 超過批處理 TTL | id |
| Video Generation | video.generated | 長視頻生成完成 | file_id、video_uri |
| Interactions API | interaction.requires_action | 需要工具調用響應 | id、required_action |
| Interactions API | interaction.completed | 多輪異步對話完成 | id、output |
| Interactions API | interaction.failed | 任意環節失敗 | id、error |
| Interactions API | interaction.cancelled | 用戶主動取消 | id |
每個事件 payload 都遵循統一結構: { "type": "batch.succeeded"， "data": { "id": "..."， "output_file_uri": "gs://..." } }。這種"type + data"的形態非常適合用一個 switch 路由器來處理，不同事件落到不同的業務管線。
📌 架構提示: 在落地時，推薦用一個 webhook 端點 + 內部事件總線（Pub/Sub、Kafka、Redis Stream）的組合，而不是爲每種事件單獨開端點。這樣既符合 Google 推薦的"快速 2xx + 異步處理"模式，也方便橫向擴展。通過 API易 apiyi.com 調用 Gemini Batch API 和 Veo 視頻生成時，事件類型與官方完全一致，你可以直接複用同一套路由代碼。
Gemini API webhooks 的安全機制和投遞保證
Gemini API webhooks 的安全設計嚴格遵循 Standard Webhooks 規範，這是一個由社區共同維護的、跨平臺的 webhook 互操作標準。這意味着如果你之前接過 Stripe、Svix、Resend 等服務的 webhook，幾乎可以無縫複用代碼。
三個關鍵 HTTP 頭
| 請求頭 | 作用 | 推薦使用方式 |
|---|---|---|
| webhook-id | 事件唯一 ID | 用作冪等鍵，防止重複處理 |
| webhook-timestamp | 事件生成時間戳（秒） | 拒絕超過 5 分鐘的請求，防 replay |
| webhook-signature | HMAC 或 JWKS 簽名 | 用 standardwebhooks 庫一鍵校驗 |
At-least-once 投遞與重試策略
Google 明確承諾至少一次投遞: 你的端點至少會收到一次每個事件的推送，也可能收到多次。任何下游寫入操作都應該按冪等去做，首選方案是把 webhook-id 作爲唯一鍵寫入數據庫或緩存。
如果你的端點返回非 2xx，Google 會在 24 小時窗口內按指數退避反覆重試。這意味着即使你的服務短暫宕機，事件也不會丟——但同樣意味着你不能用"同步阻塞處理"作爲響應，慢響應會被認爲是失敗。
簽名密鑰輪換
Static Webhook 的 HMAC 密鑰支持 REVOKE_PREVIOUS_SECRETS_AFTER_H24 模式，允許在 24 小時內同時驗證新舊兩個密鑰。這是生產環境做密鑰灰度切換的關鍵: 你可以先生成新密鑰推到所有節點，確認全部接受新密鑰後，再讓舊密鑰過期，無縫完成輪換。
🔐 安全建議: 一切 webhook 端點都應該走 HTTPS、強制校驗簽名、限制請求體大小、對慢調用做超時熔斷。如果你通過 API易 apiyi.com 同時調用 Gemini API 和其他模型，建議把所有 webhook 端點收斂到一個統一的"事件網關"服務，集中處理驗籤、去重、路由，後端按模型分流，這樣更利於合規審計和密鑰管理。
Gemini API webhooks 的核心應用場景
Gemini API webhooks 並不是爲所有 Gemini 調用準備的——同步的、毫秒級返回的 generateContent 用不上它。它真正的價值集中在三類長任務上，這也是官方博客直接點名的場景。
Deep Research 異步代理
Deep Research 類任務往往要分鐘級到小時級，涉及多輪搜索、工具調用和摘要合成。Webhook 的 interaction.requires_action 事件天然貼合這種 multi-turn 流程，你可以在每個 action 節點接收回調，異步推進下一步，而不是用一個常駐進程跟蹤整個會話。
Batch API 大批量推理
Batch API 是 Gemini 給"幾千甚至幾十萬條 prompt"準備的入口，提交後立刻返回 job ID，完成後通過 batch.succeeded 事件通知你 output_file_uri。這種模式下 webhook 的成本優勢最明顯——傳統輪詢幾千個 batch job 會瞬間打爆 API 配額。
長視頻生成 （Veo）
Veo 等長視頻生成任務通常需要數分鐘，用戶體驗上也不可能讓前端一直 spin。webhook 讓你可以提交任務後立刻返回前端"生成中，完成後會通知"，真正完成時再通過自家推送系統（WebSocket、APNs、SSE）通知用戶。
🎯 國內場景適配: 國內做 AI 視頻應用的團隊特別關心兩個問題——能否穩定調用 Gemini Veo，以及能否及時拿到完成通知。通過 API易 apiyi.com 這類 Gemini API 中轉通道，可以解決前者；而 Gemini API webhooks 的事件驅動機制，正好解決了後者，二者結合就是一套國內可落地的長視頻流水線。
決策建議: 是否要立刻遷移到 Gemini API webhooks
雖然 webhook 看起來全面優於輪詢，但是否要立刻遷移仍要看你當前的工作負載。下面這張決策矩陣可以幫你快速判斷。
| 你的現狀 | 是否建議遷移到 Gemini API webhooks |
|---|---|
| 主要用 generateContent 同步調用 | 不需要（webhook 不覆蓋此場景） |
| 偶爾用 Batch，每天幾個任務 | 可選，但收益不大 |
| 大量 Batch 任務，每天數百以上 | 強烈建議，直接消除輪詢風暴 |
| 在做 Veo 長視頻生成 | 強烈建議，體驗提升明顯 |
| 做 Deep Research / agentic 工作流 | 強烈建議，異步推進必備 |
| 多租戶 SaaS 平臺 | 強烈建議，Dynamic Webhook 完美適配 |
💡 遷移路徑: 不需要"一刀切"——可以先在新業務上用 webhook，老業務保留輪詢，逐步替換。Google 的兩種實現方式是並存的，客戶端 GET /operations 接口仍然有效。如果你打算同時用 API易 apiyi.com 調用其他模型，建議借這次機會統一所有異步任務的事件總線，減少多套通知系統的維護成本。
Gemini API webhooks 常見問題 FAQ
Gemini API webhooks 收費嗎？
根據官方博客，目前沒有爲 webhook 推送本身單獨計費，你只爲提交的 Gemini API 任務（token、視頻生成時長、Batch 處理量）付費。webhook 推送由 Google 主動發起，不消耗你的 API 調用配額。
國內服務器能直接接收 Gemini API webhooks 嗎？
可以，但前提是你的回調端點對 Google 網絡可達。如果端點完全部署在境內、且沒有公網入口，Google 無法推送。常見做法是把端點放在邊緣節點或國際可達的網關上，再回源內網；或者使用 API易 apiyi.com 這類支持 webhook 中轉的服務，把推送先接到中轉層再轉發回境內業務系統。
Gemini API webhooks 會重複推送嗎？ 怎麼去重？
會。Google 提供的是 at-least-once 投遞，任何瞬時網絡抖動或你端點的偶發 5xx 都會觸發重試。標準做法是用請求頭裏的 webhook-id 作爲冪等鍵，在數據庫或 Redis 中查重，已處理過的直接返回 2xx。
Static 和 Dynamic 兩種 webhook 可以混用嗎？
可以，而且推薦混用。常見模式是: 用 Static Webhook 做"全局兜底通知"（例如所有失敗事件都進告警），同時在關鍵任務上用 Dynamic Webhook 做"專屬路由"（例如某個 VIP 客戶的視頻生成結果直推到他自己的端點）。
如何在生產環境部署 Gemini API webhooks？
推薦架構是: HTTPS 網關 → 驗籤中間件 → 快速返回 2xx → 推消息隊列 → 後端 Worker 異步處理。這套架構能扛得住 webhook 突發流量，也方便你做監控、重放和審計。如果你已經有一套基於 API易 apiyi.com 的 AI 調用網關，把 webhook 端點合並進去會更簡潔。
Gemini API webhooks 和 Server-Sent Events 是什麼關係？
兩者解決不同問題。SSE 是"客戶端發起、服務端流式推內容"的長連接，適合實時 token 流；Webhook 是"服務端發起、跨服務器推事件"的短請求，適合任務完成通知。一個 agentic 應用經常同時用到兩者: 用戶交互層走 SSE，後臺長任務走 Webhook。
總結: Gemini API 事件驅動 Webhook 的真正意義
Gemini API webhooks 表面上是一個工程便利性的更新，本質上卻是 Google 對 AI 應用形態的一次明確表態——它認爲接下來的主流不是"一個請求一個響應"的 chat 模式，而是 Deep Research、長視頻、Batch 推理交織的 agentic 流水線。這種流水線天然需要事件驅動，Webhook 只是把這個事實從開發者自己實現挪到了平臺層。
對國內開發者來說，Gemini API webhooks 的上線還有一個額外意義: 它讓 Gemini 進一步對齊了 OpenAI、Anthropic 等同行的工程能力（這兩家此前已支持類似機制），意味着無論你選擇哪個模型，異步任務的開發範式都在收斂。配合 API易 apiyi.com 這樣的統一中轉入口，你可以把 Gemini、Claude、GPT 等模型的事件通知收到同一個事件總線，真正做到"模型可換、流水線不變"。
如果你正在做長視頻應用、批量內容生成或 agentic 自動化，現在就是遷移到事件驅動 Webhook 的最佳時機——技術成熟、官方文檔齊備、社區庫一鍵集成，遲一週做和早一週做的邊際成本幾乎爲零，但收益（輪詢消除、延遲降低、配額節省）立等可見。
📚 延伸閱讀: 官方博客詳細介紹了發佈背景: blog.google；完整的事件清單、payload 字段和 SDK 示例可參考 Gemini Cookbook: github.com/google-gemini/cookbook；簽名規範請查閱 Standard Webhooks 文檔: standardwebhooks。國內開發者如果需要穩定調用 Gemini API 的中轉通道，可以瞭解 API易官網: apiyi.com。
作者: APIYI Team — 關注 AI 大模型 API 工程實踐與異步基礎設施，提供 Gemini、Claude、GPT 多模型統一中轉服務，詳見 apiyi.com
