Gemini API 为长任务加入签名 Webhook

关键信息

Google 表示，这套 webhook 实现严格遵循 Standard Webhooks 规范，并使用 webhook-signature、webhook-id 和 webhook-timestamp 请求头进行签名，以支持幂等性并帮助防止重放攻击。系统提供“至少一次”投递保证，并会自动重试最长 24 小时；开发者可以在项目级使用 HMAC 配置 webhook，也可以在单次请求中用 JWKS 覆盖配置。

资讯摘要

Google 宣布 Gemini API 现在支持事件驱动的 Webhook，以帮助开发者更轻松地构建长时间运行的 agentic 应用。公司表示，这项改动的目标是取代低效的轮询方式，也就是开发者反复调用 GET operations 来检查任务是否完成。随着 Gemini 被用于 Deep Research、长视频生成以及 Batch API 批量处理等场景，这一问题变得更重要，因为这些任务可能持续数分钟甚至数小时。借助新机制，Gemini 可以在任务完成的瞬间向开发者服务器推送实时 HTTP POST 载荷。

Google 还强调，这套 webhook 设计遵循 Standard Webhooks 规范，并通过签名请求来提升安全性和可靠性。具体来说，请求会包含 webhook-signature、webhook-id 和 webhook-timestamp 等头部，用于支持幂等性并降低重放风险。公司同时表示，消息投递保证“至少一次”，并会自动重试最长 24 小时。开发者既可以在项目级别通过 HMAC 全局配置 webhook，也可以按请求使用 JWKS 动态覆盖配置，Google 还提供了文档和 Cookbook 供用户完成端到端集成。

资讯正文

通过 Gemini API 中的 Webhooks 降低长时间运行任务的摩擦和延迟

今天，我们让使用 Gemini API 构建复杂、长时间运行的 agentic 应用变得更简单，也更高效。我们正在引入事件驱动的 Webhooks，这是一种基于推送的通知系统，可以消除低效轮询的需要。

随着 Gemini 逐步转向 agentic 工作流和高吞吐量处理——例如 Deep Research、长视频生成，或通过 Batch API 处理成千上万条提示——这些操作可能需要几分钟甚至几小时。直到现在，开发者还不得不依赖持续轮询（例如反复调用 GET operations）来检查任务是否完成。

现在，Gemini API 可以在任务完成的瞬间，直接向你的服务器推送实时 HTTP POST 负载。

我们在设计时充分考虑了可靠性与安全性。我们的实现严格遵循 Standard Webhooks 规范。每个请求都会使用 webhook-signature、webhook-id 和 webhook-timestamp 这些头部进行签名，从而确保幂等性并防止重放攻击。我们还通过自动重试机制，保证“至少一次”投递，最长可重试 24 小时。

工作原理

你可以在项目级别全局配置 webhooks（通过 HMAC 保护），也可以针对单个请求动态覆盖它们，以路由特定任务（通过 JWKS 保护）。

下面是一个简短示例，展示如何使用 Python SDK 为批处理任务动态配置 webhook：

今天就开始使用

这项功能现已向所有使用 Gemini API 的开发者开放：

- 阅读指南：查看 Webhooks 文档，了解完整的事件目录，并学习如何保护你的端点。

- 动手实践：我们准备了一份全面的 Cookbook，帮助你构建端到端的 webhooks 集成。

来源与参考

1. 原始链接
2. Reduce friction and latency for long-running jobs with Webhooks in Gemini API