我们正在让通过 Gemini API Webhooks 构建复杂、长时间运行的智能体应用变得更加简单高效。

---

Lucia Loher

Gemini API 产品经理

Hussein Hassan Harrirou

Gemini API 工程团队

---

今天，我们正在让通过 Gemini API 构建复杂、长时间运行的智能体应用变得更加简单高效。我们推出了事件驱动的 Webhooks，这是一种基于推送的通知系统，消除了低效轮询的需求。

随着 Gemini 转向智能体工作流和高吞吐量处理——例如深度研究、长视频生成，或通过 Batch API 处理数千条提示词——操作可能需要几分钟甚至几小时。在此之前，开发者不得不依赖持续轮询（例如重复调用 `GET` 操作）来检查任务是否完成。

现在，Gemini API 可以在任务完成的那一刻，直接将实时的 HTTP POST 负载推送到你的服务器。

我们在构建此功能时充分考虑了可靠性和安全性。我们的实现严格遵循 Standard Webhooks 规范。每个请求都使用 webhook-signature、webhook-id 和 webhook-timestamp 标头进行签名，确保幂等性并防止重放攻击。我们还保证“至少一次”的投递，并在最多 24 小时内自动重试。

工作原理

你可以在项目级别全局配置 webhooks（通过 HMAC 保护），或者基于每个请求动态覆盖配置，以路由特定任务（通过 JWKS 保护）。

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

from google import genai
from google.genai import types

client = genai.Client()

file_batch_job = client.batches.create(
    model="gemini-3-flash-preview",
    src=inline_requests,
    config={
        "display_name": "My Setup",
        "webhook_config": {
            "uris": ["https://my-api.com/gemini-webhook-dynamic"],
            "user_metadata": {"job_group": "nightly-eval", "priority": "high"},
        },
    },
)

print(f"Created batch job: {file_batch_job.name}")

立即开始使用

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

• 阅读指南：查看 Webhooks 文档，探索完整的事件目录，并了解如何保护你的端点。
• 动手实践：我们准备了一份全面的 Cookbook，帮助你构建与 webhooks 的端到端集成。