Google 在 Gemini API 中引入事件驱动 Webhooks，允许服务端在任务完成时被实时推送通知，替代低效的轮询操作，从而降低延迟并简化长时间运行的 agentic 工作流集成。该实现遵循标准 Webhooks 规范，提供签名头、幂等性保护与最多 24 小时的重试保证，并支持全局与按请求动态配置两种安全模式（HMAC 与 JWKS）。
概述
– 功能：在 Gemini API 中新增事件驱动 Webhooks（推送式通知），适用于长时间运行或高并发的任务（例如深度研究、长视频生成、Batch API 批量处理）。
– 目的：替代持续轮询（重复 GET）以减少延迟和资源开销。
安全与可靠性
– 遵循 Standard Webhooks 规范。
– 请求签名头：webhook-signature、webhook-id、webhook-timestamp，用于防止重放攻击并支持幂等性。
– 投递保证：至少一次（at-least-once）投递，失败时自动重试，重试窗口最长 24 小时。
配置模式
– 全局项目级配置：使用 HMAC 保护，便于对整个项目的回调统一管理。
– 请求级动态覆盖：可在单次请求中指定目标 webhook，使用 JWKS 进行验证以实现更灵活的路由。
开发者支持资源
– 文档：提供完整事件目录与端点安全指南，建议先阅读官方 Webhooks 文档。
– Cookbook：包含端到端集成示例与实作指南，示例代码（如 Python SDK）可用于动态为 Batch 任务配置 webhook。
适用场景与建议
– 适合需要低延迟完成回调通知的长时任务与大规模并发作业。
– 推荐用签名校验与幂等处理来保证安全与可重复接收时的业务稳定性。
获取方式
– 功能现已对所有 Gemini API 开发者开放，参考官方文档与 Cookbook 即可上手。
这是向 agent 化与大规模异步工作流迈出的重要一步，但接收端需认真设计幂等与安全策略以避免重复或伪造回调。