5月5日消息,Google 正式在 Gemini API 中推出事件驱动 Webhooks,以推送式通知替代此前长时任务必须依赖的轮询模式。开发者不再需要反复调用 GET 接口检查任务状态,Gemini API 会在批处理、Deep Research、长视频生成等耗时操作完成的瞬间,通过 HTTP POST 把 payload 直接推送到指定服务器。这一能力今日起对所有 Gemini API 开发者开放,Python SDK 已同步支持 webhook_config 参数,在创建批量任务时可直接绑定回调 URI 与自定义元数据。 这次发布解决的是 Gemini 转向 Agent 工作流后浮现的核心摩擦点——单次操作动辄数分钟到数小时,Batch API 可一次处理数千个 prompt,过去开发者要么自建轮询服务消耗 API 配额,要么搭建中间层 worker 充当 webhook 桥接。Google 官方博客指出,新机制让"任务完成的瞬间"和"应用得知任务完成"之间的延迟从轮询周期(通常以秒到分钟计)压缩到一次 HTTP 推送的网络耗时,对深度研究、批量评估、长视频生成等场景尤其关键。
严格遵循 Standard Webhooks 规范
Gemini Webhooks 在协议层选择了对齐 Standard Webhooks 开源规范,这与 OpenAI 此前发布的 Webhooks 实现完全一致——每个请求都带有 webhook-id、webhook-timestamp、webhook-signature 三个标准头,既保证幂等性又防止重放攻击。可靠性侧承诺"至少一次"交付,失败请求会在 24 小时窗口内自动重试,这意味着开发者在接收端必须自己处理重复事件的去重逻辑,但相对地不必担心因临时网络故障丢失任务完成通知。
值得注意的是 Google 在认证机制上做了 OpenAI 没有的扩展。项目级全局配置走 HMAC 共享密钥,符合大多数单租户场景的常规预期;而按请求动态覆盖配置时改用 JWKS(JSON Web Key Set)进行非对称签名验证,这一选择面向的是多租户路由场景——同一个项目下不同任务可以被推送到完全独立的下游服务,每个服务用自己的公钥独立验签,无需共享主密钥。Python SDK 示例展示了如何在创建 batch job 时同时指定 webhook URI 和 user_metadata 字段,后者可用于在回调中携带自定义业务标识(如 job_group、priority),便于下游服务做路由分发。
三家头部 API 厂商的 Webhook 现状对比
把横向坐标拉开看,Webhook 已经成为长时任务 API 的标配能力,但 Google 这次属于追赶而非领跑。OpenAI 早已在 platform 层提供完整 Webhook 体系,事件类型覆盖 response.completed、batch.completed、batch.cancelled、batch.expired、batch.failed、fine_tuning.job.succeeded 等,SDK 内置 webhooks.unwrap() 方法处理签名验证,生态已经形成 codehooks.io、Pipedream、Zapier 等第三方集成路径。Anthropic 的 Message Batches API 当前仍未提供原生 Webhook,官方文档明确建议生产环境用户自行搭建轮询服务或借助 Temporal 等编排平台,社区也涌现了 openai-batch-awaiter 这类开源项目把 Batch API 的轮询包装成 Webhook 推送。从这个角度看,Gemini Webhooks 的发布意味着头部三家中只剩 Anthropic 还没补齐这块基建,Claude 系列在 Agent 化、长任务化方向的开发者体验仍存在明显短板。 JWKS 路径是 Gemini 在功能颗粒度上比 OpenAI 走得更远的一步。OpenAI 当前 Webhook 是单一项目级 signing secret,所有事件共享同一密钥;Gemini 允许在单次 API 调用中指定独立的 webhook 配置和 JWKS 校验,对多租户 SaaS、Agent 编排平台、需要根据任务类型分流到不同下游服务的场景更友好。Standard Webhooks 规范本身由 Stripe、Twilio、Shopify、Lob、Zoom 等推动,Gemini 的加入会进一步巩固这套规范在 AI API 领域的事实标准地位。
局限与待解问题
公告本身没有披露 Webhook 的具体配额限制、推送延迟 SLA、单 payload 大小上限,也未明确"至少一次"语义下重复事件的实际触发概率。24 小时重试窗口对绝大多数批处理够用,但若下游服务长时间不可用,事件最终仍会丢失,需要应用层自行设计补偿轮询作为兜底。事件目录的完整性需要在文档中确认——目前演示场景集中在 Batch API 完成事件,Deep Research、长视频生成、流式音频会话等其他长时任务是否都进入事件枚举,以及失败、超时、部分完成等异常状态如何分类发送,都还需在生产环境验证。
JWKS 模式虽然灵活,但对密钥管理、轮换、撤销链路提出了更高要求,对没有专职平台团队的小型开发者反而是负担。多 endpoint 路由能力固然强大,但若与 Gemini 自身的 Project/IAM 权限模型耦合设计不当,可能在大型组织内部产生权限边界混乱。生态侧,Webhook 真正发挥价值需要 SDK、文档、第三方集成、调试工具的整套支撑,Google 目前发布了 Cookbook 和官方文档,但相比 OpenAI 已经形成的成熟工具链,Gemini 这边的开发者样板仍处于起步阶段。模型层面,示例代码使用的 gemini-3-flash-preview 仍处预览阶段,Webhook 与 GA 模型、企业级 Vertex AI 部署的协同能力是否一致也需要进一步澄清。