Ты когда-нибудь ждал ответ от Gemini в цикле while True, отправив запрос на генерацию текста и грея экран в ожидании? Знакомо, да? Долго, дорого, неэлегантно. Ещё и лимиты кончились, а ты всё ещё висишь в поллинге.
С марта 2026 года Google закрыл эту боль: в Gemini API появились встроенные webhooks (барабанная дробь). Теперь не нужно дёргать ручку каждые 5 секунд — API сам пришлёт тебе результат, как только он будет готов. В этом гайде я покажу, как настроить приём вебхуков в Python, не проклиная всё на свете.
Важно: статья написана по состоянию на 4 мая 2026 года. API Gemini (Gemini 3 и новее) поддерживает вебхуки через механизм Standard Webhooks — это открытый стандарт, который Google использует наравне с другими облачными провайдерами. Документация актуальна для версии SDK 0.12+.
Почему polling — прошлый век (и деньги)
Представь: ты запускаешь Batch API для обработки 10 000 документов. Каждая задача выполняется 30–120 секунд. Если ты крутишь polling раз в 2 секунды, то за ожидание одной задачи ты совершаешь до 60 запросов. Умножь на 10 000 — получаешь 600 тысяч лишних HTTP-вызовов. Это не только греет кошелёк (каждый запрос — копейка), но и нагружает твой сервер.
В режиме Flex (самый дешёвый тариф) Google рекомендует именно вебхуки — они снижают стоимость опроса до нуля. Как я писал в сравнении Flex и Priority, на фоновых задачах экономия достигает 50%, и вебхуки — главный рычаг этой экономии.
Как работают вебхуки в Gemini API
Google реализовал поддержку Standard Webhooks — открытого протокола для отправки уведомлений. Если ты уже знаком с вебхуками Stripe или GitHub, то будешь чувствовать себя как дома.
Механика простая:
- Ты создаёшь endpoint (URL твоего сервера), который принимает POST-запросы.
- Регистрируешь его в Google Cloud Console или через SDK.
- При отправке запроса к Gemini (например,
models/generateContentс параметромasync=true) ты указываешьwebhook_url. - Когда задача завершилась, Gemini шлёт POST на твой URL с payload и подписью.
- Ты верифицируешь подпись и обрабатываешь ответ.
webhook-id, webhook-timestamp и webhook-signature. Подпись вычисляется на основе HMAC-SHA256 с секретом, доступным только тебе. Никто не сможет подделать уведомление.Настройка: пошагово (чтобы не споткнуться)
1Подготовь endpoint
Тебе нужен HTTPS-сервер. В продакшене — обязательно с нормальным сертификатом (Let's Encrypt, не самоподписанный). Для простоты я покажу на FastAPI, но можно на Flask, Django, Express — без разницы.
2Получи секрет для вебхуков
Зайди в Google Cloud Console → AI Platform → Gemini → Webhooks. Там сгенерируй ключ. Сохрани его в переменную окружения GEMINI_WEBHOOK_SECRET.
Warning: никогда не храни секрет в коде. Используй .env или secrets manager. Если секрет утечёт — злоумышленник сможет имитировать вебхуки от Google.
3Напиши приёмщик вебхуков на Python
Вот минимальный рабочий код на FastAPI. Я намеренно сделал его без излишеств, но с верификацией.
import os
import hmac
import hashlib
import json
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()
SECRET = os.environ["GEMINI_WEBHOOK_SECRET"].encode()
def verify_signature(payload: bytes, signature_header: str, timestamp: str, msg_id: str) -> bool:
"""Standard Webhooks verification"""
signed_content = f"{msg_id}.{timestamp}.".encode() + payload
expected_sig = hmac.new(SECRET, signed_content, hashlib.sha256).hexdigest()
# заголовок может содержать список подписей через пробел, берём первую
received_sig = signature_header.split(" ")[0].split(",")[0]
return hmac.compare_digest(expected_sig, received_sig)
@app.post("/webhook/gemini")
async def handle_webhook(request: Request):
body = await request.body()
msg_id = request.headers.get("webhook-id", "")
timestamp = request.headers.get("webhook-timestamp", "")
signature = request.headers.get("webhook-signature", "")
if not verify_signature(body, signature, timestamp, msg_id):
raise HTTPException(status_code=401, detail="Invalid signature")
# payload - это JSON с результатами генерации
data = json.loads(body)
# обработай ответ: сохрани в БД, отправь в очередь и т.д.
print("Received webhook:", data)
# обязательно верни 200, иначе Google будет ретраить
return {"status": "ok"}webhook-id и не обрабатывай дубли. Используй Redis или БД для хранения обработанных ID.4Зарегистрируй URL в Gemini SDK
Теперь, когда твой эндпоинт висит, нужно сказать Gemini, куда слать уведомления. Сделать это можно двумя способами: через консоль (глобально для всех запросов) или непосредственно в каждом запросе (рекомендую).
Пример с указанием вебхука при отправке через Python SDK:
import google.generativeai as genai
# Не забудь импортировать нужные модули!
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel("gemini-2.5-pro")
response = model.generate_content(
"Напиши статью про вебхуки",
# асинхронный режим + вебхук
# (параметр 'async_=True' доступен в SDK 0.12+)
async_=True,
webhook_url="https://my-server.com/webhook/gemini"
)
# запрос сразу возвращает operation ID, а результат придёт в вебхук
print("Task ID:", response.operation_id)После этого Gemini отправляет POST на твой URL, когда генерация завершится (или упадёт с ошибкой). В теле ты получишь полный ответ — как если бы ты синхронно вызвал generate_content.
Что пошло не так? Типовые ошибки (и как их избежать)
| Ошибка | Симптом | Решение |
|---|---|---|
| Проверка подписи падает | 401 от твоего endpoint | Убедись, что секрет правильный и не содержит лишних пробелов. Используй одну и ту же кодировку (UTF-8). |
| Вебхук не приходит вообще | Тишина | Проверь, что твой endpoint доступен из интернета (не за NAT). Используй ngrok для локального теста. |
| Вебхук приходит, но данные пустые | Payload без candidates | Скорее всего, ошибка при генерации. В вебхуке будет поле error — смотри его. |
| Дублирующиеся вебхуки | Обрабатываешь один ответ дважды | Внедри идемпотентность по webhook-id. |
Продакшн-советы от автора
- Таймаут. Твой endpoint должен отвечать за менее 10 секунд. Если нужно обработать долго — ставь задачу в очередь (Redis/Celery) и сразу возвращай 200. Иначе Google воспримет таймаут как неудачу и начнёт ретраить.
- Ретраи. По умолчанию Google делает 3 попытки с экспоненциальной задержкой. Если ты знаешь, что твой endpoint временно лёг — лучше верни 5xx, это корректно обработается.
- Мониторинг. Обязательно добавь метрики: количество принятых вебхуков, ошибки верификации, время обработки. Если дёргается — ты узнаешь первым.
- Логирование. Логируй
webhook-idи статус ответа. Это спасёт при дебаггинге.
Если ты используешь AI Bridge для управления компьютером, вебхуки идеально впишутся: ты сможешь отдать долгую задачу (например, сгенерировать 1000 токенов) и получить результат, не блокируя основной поток.
Сравнение с альтернативами
Давай честно: можно было и без вебхуков обойтись, используя polling через очередь типа RabbitMQ. Но посмотри на затраты: с вебхуками ты платишь только за сами вызовы Gemini, а не за пустые запросы. Если ты уже настроил свою систему на push-уведомлениях (как в статье про GigaChat и n8n), то миграция на Gemini-вебхуки займёт 15 минут.
Бонус: Google AI Studio поддерживает тестирование вебхуков прямо из интерфейса. Можешь отправить тестовый payload на свой endpoint, не запуская код — это отличный способ отладить приёмник. Инструкцию по первому запуску в AI Studio я давал в туториале.
Коротко о главном
Вебхуки в Gemini API — это не просто фича, а фундаментальная смена подхода: от «дёрни меня» к «я сам приду». Экономишь ресурсы, время и нервы. Используй Standard Webhooks, не забудь про идемпотентность и подпись. А если Google AI когда-нибудь сам начнёт вебхучить тебе новые идеи для стартапов — скажи спасибо, что прочитал этот гайд.
