Webhooks в Gemini API: push-уведомления для долгих задач без polling

Сегодня мы делаем разработку сложных агентных приложений с Gemini API проще и эффективнее. Мы представляем event-driven Webhooks — систему уведомлений на основе push, которая устраняет необходимость в неэффективном polling.

По мере того как Gemini смещается в сторону agentic workflows и высоконагруженной обработки — например, Deep Research, генерации длинных видео или обработки тысяч запросов через Batch API — операции могут занимать минуты или даже часы. До сих пор разработчикам приходилось полагаться на постоянный polling, например многократно вызывать операции GET, чтобы проверить, завершилась ли задача.

Теперь Gemini API может просто отправить вашему серверу HTTP POST payload в реальном времени в тот момент, когда задача завершится.

Мы строили это с приоритетом надежности и безопасности. Наша реализация строго соответствует спецификации Standard Webhooks. Каждый запрос подписывается заголовками webhook-signature, webhook-id и webhook-timestamp, что обеспечивает идемпотентность и защищает от replay attacks. Мы также гарантируем доставку по принципу «at-least-once» с автоматическими повторными попытками в течение до 24 часов.

Как это работает

Вы можете настраивать webhooks глобально на уровне проекта — с защитой через HMAC — или динамически переопределять их на уровне отдельного запроса, чтобы направлять конкретные задания — с защитой через JWKS.

Вот краткий пример того, как можно динамически настроить webhook для batch-задачи с помощью Python SDK:

Начните уже сегодня

Эта функция уже доступна всем разработчикам, использующим Gemini API:

• Изучите руководство: откройте документацию по Webhooks, чтобы ознакомиться с полным каталогом событий и узнать, как защитить свои endpoints.
• Практика: мы подготовили подробный Cookbook, который поможет вам собрать end-to-end интеграцию с webhooks.

Материал — перевод статьи с английского.

Оригинал: Reduce friction and latency for long-running jobs with Webhooks in Gemini API