Разбор вебхуков Gemini API: 4 механизма событийных уведомлений, запущенных 4 мая

4 мая 2026 года Google в своем официальном блоге объявила: «Событийно-ориентированные вебхуки теперь доступны в Gemini API». Спустя два дня, 6 мая в 10:00 по пекинскому времени, это письмо от Google AI Studio пришло в почтовые ящики разработчиков по всему миру, ознаменовав полноценный запуск вебхуков Gemini API для всех пользователей.

Для многих команд, занимающихся Deep Research, генерацией длинных видео или масштабным пакетным (Batch) выводом, это обновление «инфраструктурного уровня». Это не новая модель и не новые параметры, но оно полностью меняет подход к тому, как выстраивается диалог с «долгоиграющими» задачами ИИ.

В этой статье, основываясь на данных из официального блога Google и Gemini Cookbook, мы разберем типы событий Gemini API webhooks, два способа их настройки, механизм проверки подписи и код для быстрого старта. Также обсудим, что это значит для локальных разработчиков.

Что такое Gemini API webhooks: кратко об управлении событиями

Вебхуки Gemini API — это по сути механизм доставки событий через HTTP POST. Когда ваша пакетная задача, задача по генерации видео или асинхронный диалог завершаются, Gemini API самостоятельно отправляет подписанное JSON-уведомление на заранее зарегистрированный вами адрес сервера. Вам больше не нужно постоянно отправлять GET-запросы для опроса статуса задачи.

Такой подход «обратного вызова» не нов для традиционной разработки, но в контексте ИИ-вычислений он имеет огромное значение. Текущие флагманские функции Gemini — Deep Research, генерация длинных видео Veo и Batch API — выполняются от нескольких минут до нескольких часов. Если продолжать использовать опрос (polling), клиенту пришлось бы поддерживать долгоживущие соединения, таймеры и логику восстановления после ошибок, что привело бы к росту затрат на эксплуатацию и нерациональному расходу квот API.

🎯 Суть в двух словах: Вебхуки Gemini API превращают процесс «я закончил?» из бесконечных вопросов клиента в активное уведомление от сервера. Разработчику достаточно создать эндпоинт для обратного вызова и ждать сигнала. Команды, работающие через такие сервисы-прокси API, как APIYI (apiyi.com), также могут использовать вебхуки для сокращения количества запросов на опрос через международные каналы, что значительно снижает задержки и потребление трафика.

Важно отметить, что вебхуки Gemini API передают «тонкую нагрузку» (thin payload) — они сообщают ID задачи, статус и указатель на файл с результатом (например, output_file_uri), но не вставляют в тело POST-запроса десятки мегабайт видео или тысячи строк пакетного вывода. Это осознанное решение: оно снижает затраты на передачу данных при повторных попытках и делает управление правами доступа более прозрачным.

Почему вебхуки Gemini API положили конец «эпохе поллинга»

Чтобы понять ценность вебхуков Gemini API, нужно сначала осознать, во сколько обходится постоянный опрос (polling). До появления вебхуков типичный процесс пакетной обработки (Batch) выглядел так: отправка задачи → получение ID операции → setInterval с запросом GET каждые 30 секунд → невозможность уйти домой, пока статус не сменится на SUCCEEDED. Для одной задачи это еще терпимо, но в продакшене такая схема быстро превращается в проблему.

В таблице ниже приведено сравнение традиционного поллинга и событийно-ориентированных вебхуков по нескольким критериям. Это именно те преимущества перехода, на которых делает акцент Google в своем официальном блоге.

Критерий сравнения	Традиционный поллинг	Вебхуки Gemini API (событийные)
Задержка уведомлений	Зависит от интервала (обычно 10–60 сек)	Миллисекунды (сразу после завершения)
Расход квот API	Каждый запрос учитывается в квоте на чтение	Push-уведомление от Google, квота не тратится
Сложность клиента	Нужны таймеры, автоматы состояний, ретраи	Нужен только HTTP POST эндпоинт + проверка подписи
Масштабируемость	«Шторм запросов» при тысячах задач	События приходят независимо, легко масштабируются
Восстановление	Клиент должен реализовывать сам	Автоматические ретраи с экспоненциальной задержкой (до 24 ч)
Сценарии	Короткие задачи, низкая нагрузка	Длинные задачи, высокая нагрузка, агентные пайплайны

Как видно из таблицы, вебхуки Gemini API — это не просто «экономия кода на поллинг». Фактически, они переносят ответственность за «оркестрацию задач» с клиента на сторону сервера. Для команд, запускающих агентные рабочие процессы, комбинация вебхуков с Cloud Run, Cloud Functions или любым другим Serverless-решением позволяет добиться полностью асинхронной работы без необходимости держать «длинные» соединения.

💡 Миграция с поллинга: Если ваш текущий код построен вокруг GET /operations, переход на вебхуки потребует лишь замены «цикла опроса» на «маршрутизатор обратных вызовов». Бизнес-логика практически не меняется. При работе с Gemini API через сервис-прокси APIYI (apiyi.com) вы можете направить вебхук прямо в свою внутреннюю сеть. Это сохраняет все преимущества событийной модели и избавляет от нестабильности при кросс-граничных соединениях.

Два способа настройки вебхуков Gemini API: Static vs Dynamic

Gemini API поддерживает два способа регистрации, предназначенных для «глобальных уведомлений» и «маршрутизации по задачам». Понимание разницы между ними напрямую влияет на вашу стратегию управления ключами и проверки подписей.

Static Webhook: подписка на события уровня проекта

Static Webhook регистрируется один раз через WebhookService API и действует для всех событий в проекте. Это удобно для сценариев «широковещательной рассылки», например, отправки всех событий batch.succeeded в Slack или синхронизации сгенерированных видео с вашим CMS.

Что касается безопасности: Static Webhook использует симметричный ключ HMAC. Google возвращает секрет подписи (signing secret) только один раз — его нужно немедленно сохранить в систему управления секретами, иначе придется удалять и пересоздавать вебхук.

Dynamic Webhook: точечная маршрутизация на уровне запроса

Dynamic Webhook — это более гибкий подход: вы указываете URL в поле webhook_config при каждом создании задачи. Google отправит уведомление именно по этому адресу. Это идеально подходит для SaaS-решений с мультиарендностью (multi-tenancy), где задачи разных клиентов должны приходить на разные эндпоинты.

Dynamic Webhook также позволяет передавать поле user_metadata (любые пары ключ-значение, например {"job_group": "nightly-eval"}), которые Google вернет при отправке уведомления. Это избавляет от необходимости вести отдельную таблицу соответствия «задача — бизнес-контекст».

Для подписи Dynamic Webhook использует асинхронный публичный ключ JWKS (RS256). Ваш сервис просто забирает ключ с адреса generativelanguage.googleapis.com/.well-known/jwks.json, хранить симметричные ключи не нужно.

Критерий	Static Webhook	Dynamic Webhook
Регистрация	Однократная через WebhookService API	Указывается в каждом запросе
Область действия	Весь проект	Отдельная задача
Алгоритм подписи	Симметричный ключ HMAC	Публичный ключ JWKS / RS256
Управление ключами	Возвращается один раз, нужно хранить	Не нужно, получение через эндпоинт
user_metadata	Не поддерживается	Поддерживается (любые данные)
Сценарии	Глобальные уведомления, Slack, архивы	Мультиарендность, маршрутизация по клиентам
Рекомендация	Для внутренних пайплайнов	Для SaaS-платформ и внешних сервисов

🎯 Совет по выбору: Если вы работаете внутри одной команды, выбирайте Static Webhook. Если вы строите SaaS-платформу с множеством клиентов — Dynamic Webhook. При использовании APIYI (apiyi.com) для доступа к Gemini API оба режима работают «из коробки»: заголовки подписи и структура событий полностью соответствуют официальной документации, так что переход будет бесшовным.

Руководство по вебхукам Gemini API: подписка за 5 строк кода

Ниже представлен минималистичный пример кода: от создания статического вебхука до проверки подписи и получения событий. Цель — помочь вам запустить рабочий цикл обработки событий менее чем за 10 минут.

Создание вебхука для событий Gemini API с помощью Python SDK

from google import genai
import os

client = genai.Client()

# Создаем вебхук для отслеживания завершения пакетных задач и генерации видео
webhook = client.webhooks.create(
    subscribed_events=["batch.succeeded", "video.generated"],
    name="prod_global_notify",
    uri="https://your-server.example.com/gemini/webhook",
)

# signing_secret возвращается только один раз, обязательно сохраните его сразу
os.environ["WEBHOOK_SIGNING_SECRET"] = webhook.new_signing_secret

Этот код выполняет две задачи: регистрирует глобальный эндпоинт для прослушивания событий завершения пакетной обработки и генерации видео, а также сохраняет секретный ключ подписи, полученный от Google, в переменные окружения. В продакшене настоятельно рекомендуется хранить секреты в Secret Manager, Vault или аналогичных сервисах, а не в репозитории кода или логах.

Прием и проверка подписи на Node.js + Express

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.WEBHOOK_SIGNING_SECRET);

app.post("/gemini/webhook", express.raw({ type: "*/*" }), (req, res) => {
  try {
    // Проверка подписи события
    const event = wh.verify(req.body, req.headers);
    console.log("событие:", event.type, "данные:", event.data);
    res.status(200).send("ok");
  } catch (e) {
    res.status(400).send("неверная подпись");
  }
});

app.listen(8080);

Важные моменты: обязательно используйте express.raw для получения исходного потока байтов для проверки подписи, иначе JSON-парсинг нарушит целостность данных. Ответ 2xx должен быть отправлен в течение нескольких секунд; любую тяжелую логику (запись в БД, вызовы внешних API) следует переносить в очередь задач. Также рекомендуется отклонять запросы, временная метка которых старше 5 минут — это стандартная практика защиты от повторов (replay attacks) в Standard Webhooks.

🚀 Совет из практики: Если ваш сервис развернут в РФ, а эндпоинт вебхука должен быть доступен для Google напрямую, рекомендую выставить эндпоинт на зарубежном узле или через CDN с обратным проксированием в локальную сеть. Либо используйте сервис-прокси API, такой как APIYI (apiyi.com), который поддерживает как вызов моделей Gemini, так и проксирование обратных вызовов. Это позволит принимать пуши вебхуков на промежуточном слое и пересылать их в локальную сеть, избавляя от проблем с NAT и настройкой SSL.

Обзор типов событий, поддерживаемых вебхуками Gemini API

В настоящее время вебхуки Gemini API охватывают три основные категории состояний длительных задач. В таблице ниже приведен список событий, указанный в официальном Cookbook.

Группа событий	Имя события	Условие срабатывания	Ключевые поля payload
Batch API	batch.succeeded	Пакетная задача успешно завершена	id, output_file_uri
Batch API	batch.failed	Ошибка пакетной задачи	id, error
Batch API	batch.cancelled	Отмена пользователем	id
Batch API	batch.expired	Истек срок TTL задачи	id
Video Generation	video.generated	Генерация видео завершена	file_id, video_uri
Interactions API	interaction.requires_action	Требуется ответ инструмента	id, required_action
Interactions API	interaction.completed	Завершена многоходовая асинхронная беседа	id, output
Interactions API	interaction.failed	Ошибка на любом этапе	id, error
Interactions API	interaction.cancelled	Отмена пользователем	id

Каждый payload события следует единой структуре: { "type": "batch.succeeded", "data": { "id": "...", "output_file_uri": "gs://..." } }. Такой формат "type + data" идеально подходит для использования роутера (switch), который направляет разные события в соответствующие бизнес-конвейеры.

📌 Архитектурный совет: При реализации рекомендуется использовать комбинацию одного эндпоинта вебхука и внутренней шины событий (Pub/Sub, Kafka, Redis Stream), вместо создания отдельного эндпоинта для каждого типа события. Это соответствует рекомендованному Google подходу "быстрый ответ 2xx + асинхронная обработка" и упрощает масштабирование. При использовании APIYI (apiyi.com) для вызова Gemini Batch API и генерации видео Veo типы событий полностью совпадают с официальными, поэтому вы можете использовать одну и ту же логику маршрутизации.

Механизмы безопасности и гарантии доставки Gemini API webhooks

Безопасность вебхуков Gemini API строго соответствует спецификации Standard Webhooks — это общепринятый кроссплатформенный стандарт, поддерживаемый сообществом. Это значит, что если вы уже работали с вебхуками Stripe, Svix или Resend, то сможете практически без изменений использовать уже написанный код.

Три ключевых HTTP-заголовка

Заголовок	Назначение	Рекомендация
webhook-id	Уникальный ID события	Используйте как ключ идемпотентности, чтобы избежать дублирования обработки
webhook-timestamp	Временная метка (в секундах)	Отклоняйте запросы старше 5 минут для защиты от атак повторного воспроизведения (replay)
webhook-signature	HMAC или JWKS подпись	Проверяйте с помощью библиотеки standardwebhooks

Стратегия доставки «минимум один раз» (At-least-once) и повторы

Google гарантирует доставку «минимум один раз»: ваш эндпоинт получит каждое событие как минимум однажды, но возможны и повторные доставки. Любые операции записи в базу данных должны быть идемпотентными: лучший способ — использовать webhook-id в качестве уникального ключа при записи в БД или кэш.

Если ваш эндпоинт возвращает код, отличный от 2xx, Google будет повторять попытки в течение 24 часов с экспоненциальной задержкой. Это значит, что даже при кратковременном сбое вашего сервиса события не потеряются. Однако это также означает, что вы не должны использовать «синхронную блокирующую обработку» в качестве ответа: медленный ответ будет расценен как ошибка.

Ротация ключей подписи

HMAC-ключи для статических вебхуков поддерживают режим REVOKE_PREVIOUS_SECRETS_AFTER_H24, который позволяет проверять подписи как новым, так и старым ключом в течение 24 часов. Это критически важно для безопасной ротации в продакшене: вы можете сгенерировать новый ключ, распространить его на все узлы, убедиться, что всё работает, и только потом деактивировать старый ключ.

🔐 Совет по безопасности: Все эндпоинты вебхуков должны работать через HTTPS, принудительно проверять подписи, ограничивать размер тела запроса и иметь таймауты для медленных вызовов. Если вы используете APIYI (apiyi.com) для вызова Gemini API и других моделей, рекомендую свести все эндпоинты вебхуков в единый «шлюз событий». Это позволит централизованно проверять подписи, дедуплицировать запросы и маршрутизировать их по моделям, что упрощает аудит и управление ключами.

Основные сценарии использования Gemini API webhooks

Вебхуки Gemini API предназначены не для всех типов вызовов — для синхронного generateContent с ответом за миллисекунды они не нужны. Их реальная ценность раскрывается в трех типах длительных задач, которые официально выделяет Google.

Асинхронные агенты для Deep Research

Задачи типа Deep Research часто занимают от нескольких минут до часов, включая многоэтапный поиск, вызов инструментов и синтез данных. Событие interaction.requires_action идеально подходит для таких многоходовых процессов: вы можете получать колбэк на каждом узле действия и асинхронно переходить к следующему шагу, вместо того чтобы держать постоянно запущенный процесс для отслеживания всей сессии.

Массовый вывод через Batch API

Batch API — это решение Gemini для обработки «тысяч или даже сотен тысяч промптов». После отправки вы сразу получаете ID задачи, а по завершении — уведомление через событие batch.succeeded с output_file_uri. В этом режиме преимущество вебхуков очевидно: традиционный опрос (polling) тысяч задач мгновенно исчерпал бы ваши лимиты API.

Генерация длинных видео (Veo)

Задачи по генерации длинных видео (например, через Veo) обычно занимают несколько минут, и заставлять пользователя ждать на фронтенде — плохая практика. Вебхуки позволяют отправить задачу и сразу вернуть ответ «Генерация запущена, мы уведомим вас по готовности», а по завершении — отправить уведомление через вашу собственную систему (WebSocket, APNs, SSE).

🎯 Адаптация для локальных задач: Команды, разрабатывающие AI-видеосервисы, часто беспокоятся о двух вещах: стабильности вызова Gemini Veo и своевременном получении уведомлений о завершении. Использование APIYI (apiyi.com) в качестве прокси-сервиса для Gemini API решает первую проблему, а событийная модель Gemini API webhooks — вторую. Вместе они образуют полноценный пайплайн для работы с длинными видео.

Рекомендации по принятию решения: стоит ли немедленно переходить на вебхуки Gemini API

Хотя вебхуки кажутся гораздо более эффективным решением, чем поллинг (опрос состояния), необходимость немедленного перехода зависит от вашей текущей рабочей нагрузки. Матрица решений ниже поможет вам быстро сориентироваться.

Ваша ситуация	Рекомендация по переходу на вебхуки Gemini API
Используете в основном синхронные вызовы generateContent	Не нужно (вебхуки не покрывают этот сценарий)
Изредка используете Batch, несколько задач в день	Опционально, но выгода невелика
Большой объем Batch-задач, сотни и более в день	Настоятельно рекомендуется, устраняет «шторм» запросов
Работаете с генерацией длинных видео через Veo	Настоятельно рекомендуется, заметное улучшение UX
Используете Deep Research / агентские рабочие процессы	Настоятельно рекомендуется, необходимо для асинхронности
Мультиарендная SaaS-платформа	Настоятельно рекомендуется, идеально подходит для Dynamic Webhook

💡 Путь миграции: Не обязательно переводить всё сразу — можно начать использовать вебхуки для новых задач, оставив старые на поллинге, и постепенно проводить замену. Оба способа реализации от Google могут сосуществовать, интерфейс GET /operations для клиентов остается рабочим. Если вы планируете использовать APIYI (apiyi.com) для вызова других моделей, рекомендую воспользоваться этим моментом, чтобы унифицировать шину событий для всех асинхронных задач и снизить затраты на поддержку нескольких систем уведомлений.

FAQ по вебхукам Gemini API

Взимается ли плата за вебхуки Gemini API?

Согласно официальному блогу, на данный момент отдельная плата за саму отправку вебхуков не взимается. Вы платите только за отправленные задачи Gemini API (токены, длительность генерации видео, объем пакетной обработки). Отправка вебхука инициируется Google и не расходует вашу квоту на вызовы API.

Могут ли серверы в Китае напрямую принимать вебхуки Gemini API?

Да, но при условии, что ваш эндпоинт обратного вызова доступен из сети Google. Если эндпоинт развернут полностью внутри страны и не имеет доступа из публичной сети, Google не сможет отправить уведомление. Распространенная практика — разместить эндпоинт на пограничном узле или шлюзе с доступом к международной сети, а затем перенаправить запрос во внутреннюю сеть. Также можно использовать сервис-прокси API, такой как APIYI (apiyi.com), который поддерживает пересылку вебхуков, принимая их на промежуточном уровне и перенаправляя в вашу внутреннюю систему.

Будут ли вебхуки Gemini API отправляться повторно? Как избежать дублирования?

Да. Google использует доставку «как минимум один раз» (at-least-once), поэтому любые кратковременные сетевые сбои или случайные ошибки 5xx на вашем эндпоинте приведут к повторным попыткам. Стандартный подход — использовать webhook-id из заголовка запроса в качестве ключа идемпотентности. Проверяйте его в базе данных или Redis: если запрос уже был обработан, просто верните код 2xx.

Можно ли использовать статические и динамические вебхуки одновременно?

Да, и это рекомендуется. Типичный сценарий: использование статического вебхука для «глобальных уведомлений» (например, все ошибки отправляются в систему оповещения), а динамического вебхука — для «целевой маршрутизации» критически важных задач (например, результаты генерации видео для VIP-клиента отправляются напрямую на его собственный эндпоинт).

Как развернуть вебхуки Gemini API в производственной среде?

Рекомендуемая архитектура: HTTPS-шлюз → промежуточное ПО для проверки подписи → быстрый ответ 2xx → очередь сообщений → асинхронная обработка фоновым воркером. Такая архитектура способна выдержать резкие скачки трафика вебхуков, а также упрощает мониторинг, повторы и аудит. Если у вас уже есть шлюз для вызова AI-моделей на базе APIYI (apiyi.com), будет логично интегрировать эндпоинт вебхуков туда.

Как соотносятся вебхуки Gemini API и Server-Sent Events (SSE)?

Они решают разные задачи. SSE — это долгоживущее соединение, инициируемое клиентом для потоковой передачи контента с сервера, что идеально подходит для потоков токенов в реальном времени. Вебхук — это короткий запрос, инициируемый сервером для передачи событий между серверами, что лучше подходит для уведомлений о завершении задач. Агентные приложения часто используют и то, и другое: уровень взаимодействия с пользователем работает через SSE, а фоновые длительные задачи — через вебхуки.

Итог: истинное значение событийно-ориентированных вебхуков Gemini API

Вебхуки Gemini API на первый взгляд кажутся лишь инженерным удобством, но по сути это четкий сигнал от Google о векторе развития AI-приложений. Компания признает, что мейнстримом становится не модель чата «один запрос — один ответ», а агентные конвейеры, объединяющие глубокий поиск (Deep Research), длинные видео и пакетные вычисления. Такие конвейеры по своей природе требуют событийно-ориентированного подхода, и вебхуки просто переводят эту необходимость с уровня реализации разработчиком на уровень платформы.

Для разработчиков это также означает, что Gemini выравнивает свои инженерные возможности с OpenAI и Anthropic. Это значит, что парадигма разработки асинхронных задач унифицируется независимо от выбора модели. Используя единый шлюз, такой как APIYI (apiyi.com), вы можете собирать уведомления от Gemini, Claude, GPT и других моделей в единую шину событий, добиваясь того, чтобы «модели можно было менять, а конвейер оставался прежним».

Если вы занимаетесь разработкой приложений для работы с длинными видео, пакетной генерацией контента или агентной автоматизацией, сейчас самое время перейти на событийно-ориентированные вебхуки. Технология зрелая, документация полная, а интеграция через библиотеки выполняется в один клик. Преимущества (отказ от опроса, снижение задержек, экономия квот) будут заметны сразу.

📚 Дополнительное чтение: Подробности выпуска в официальном блоге: blog.google; полный список событий, полей полезной нагрузки и примеры SDK доступны в Gemini Cookbook: github.com/google-gemini/cookbook; спецификации подписи см. в документации Standard Webhooks: standardwebhooks. Если вам нужен стабильный канал для вызова Gemini API, посетите сайт APIYI: apiyi.com.

---

Автор: Команда APIYI — специализируемся на инженерных практиках работы с API больших языковых моделей и асинхронной инфраструктуре. Предоставляем единый шлюз для моделей Gemini, Claude и GPT. Подробности на apiyi.com