Gemini API Webhooks 上線：長任務 AI 不該只靠輪詢等結果

凌晨 2:13，一個 Gemini API 批次工作終於跑完。

以前你的服務可能每隔幾秒問一次：好了嗎？好了嗎？好了嗎？現在 Google 給了另一條路：讓 Gemini API 在狀態改變時，把帶簽章的 HTTP POST 推到你的接收端點。

Google 在 2026 年 5 月 4 日宣布 Gemini API Webhooks，目標是處理長時間執行的 AI 工作。Google 舉的例子包括 Deep Research 類工作、長影片生成、大量 Batch API 處理，以及 Interactions API 裡的長時間操作。這些任務可能跑幾分鐘，也可能跑幾小時；用一般請求回應心態去等，會把應用程式寫成一串脆弱的輪詢器。

這則更新值得看，因為它把 AI 長任務拉回很務實的軟體工程問題：任務完成時，誰通知誰？通知能不能驗證？通知失敗會怎麼重試？同一個事件送兩次時，你的系統會不會做兩次？

先把等待這件事拆開

Gemini API Webhooks 處理的是工作狀態怎麼回到你的產品，而非模型能力本身。

以批次任務為例，應用程式先提交 job，接著要知道它是成功、失敗、取消、過期，還是需要人類或函式接手。過去最直覺的方法是輪詢：存下 operation ID，固定時間打一次 status API，直到狀態變成 done。

輪詢能用，但代價很清楚。任務少時只是麻煩；任務多、時間長、狀態多時，就會變成背景流量、排程器、timeout、重試和支援查詢的組合題。

Webhook 的做法是反過來。你先準備一個接收端，訂閱事件。當 Gemini API 裡支援的工作狀態改變，Google 會把事件推到你的 URL。Google 文件列出的事件包含 batch.succeeded、batch.failed、interaction.completed、interaction.requires_action、video.generated 等。

Webhook 改的是任務完成後那一段

Google 文件裡有兩種配置方式。

第一種是 static webhook。你在專案層級建立接收端點，拿到只會顯示一次的 signing secret，接著用它驗證收到的請求。這適合固定接收同一類事件的後端服務。

第二種是 dynamic webhook。你可以在特定請求裡放 webhook config，把某次 batch 或長任務導到指定接收端點。Google 文件說 dynamic webhook 使用 JWKS 驗證簽章，適合把不同 job group、優先級或工作流送到不同處理路徑。

無論哪一種，Google 的設計都有幾個明確邊界。每個 webhook request 需要驗簽；接收端要在幾秒內回 2xx，不然會觸發重試；失敗請求會用 exponential backoff 自動重試 24 小時；payload 是 thin payload，通常帶狀態、job ID 和結果指標，完整輸出則要沿著指標另行取得。

這些細節比「少輪詢」更重要。因為它們決定你的產品要在哪裡記錄狀態、在哪裡抓結果、在哪裡處理失敗。

這裡最容易誤讀的是可靠性

Webhook 讓等待變得比較乾淨，但它沒有替你的系統保證 exactly-once。

Google 文件的說法是 at-least-once delivery。這代表事件可能送超過一次。文件也明確建議用 webhook-id 做去重，並檢查 webhook-timestamp，拒絕太舊的 payload，降低 replay attack 風險。

接收端也不能把所有工作都塞在 request handler 裡慢慢做。比較穩的做法是：先驗簽，確認 event 可以接受，快速回 2xx，然後把後續解析、抓結果、更新資料庫、通知使用者的工作丟進自己的佇列。

換句話說，Webhook 把「等結果」從前端或排程器移到伺服器對伺服器的事件路徑。這條路更適合長任務，但也要求團隊把事件處理當成正式環境路徑管理。

導入前做一個五步小測試

如果你正在把 Gemini API 長任務從輪詢改成 webhook，可以先用這張表檢查自己的系統：

步驟	輪詢路徑	Webhook 路徑	導入前要測什麼
啟動任務	提交 job，存 operation ID	提交 job，指定 static 或 dynamic webhook	job ID、回呼 URL、metadata 是否能對回同一個任務
等待狀態	固定時間查 status	收到 signed event	驗簽失敗時是否拒收，成功時是否快速 2xx
取得結果	status done 後再抓結果	從 thin payload 拿 result pointer 再抓	抓結果失敗時是否會重試或進人工佇列
處理失敗	polling timeout 或查到 failed	Google 重試失敗回呼，最多 24 小時	duplicate event 是否只處理一次
支援查詢	看 polling log	看 webhook-id、timestamp、job status、result fetch log	客服或工程師能不能還原任務卡在哪裡

這張表不要求所有團隊立刻放棄輪詢。輪詢在小規模、低頻、內部工具裡仍然簡單可靠。Webhook 比較適合的，是任務量變大、等待時間變長、產品需要即時狀態更新，或工作流已經有佇列和事件處理基礎的團隊。

所以評估 Gemini API Webhooks 時，不要只問「可不可以少打一堆 GET」。更好的檢查方式是：你的接收端能不能驗證每一個事件、快速承認、晚點處理、重複不亂、漏接可查。

如果答案是可以，Webhook 會讓長任務 AI 更像可營運的後端工作。若答案還不確定，先保留輪詢對帳路徑，直到回呼路徑經過失敗測試。

林子睿（編輯：廖玄同），《Gemini API Webhooks 上線：長任務 AI 不該只靠輪詢等結果》，矽基前沿 [Si]gnals，2026-05-14。https://signals.tw/articles/gemini-api-webhooks-long-running-agents/