Webhooki w Gemini API: jak działają i kiedy zastępują polling
Webhooki w Gemini API: jak działają, kiedy zastępują polling, jak zabezpieczyć endpoint i ile realnie daje Batch API. Ceny i zasady dostawy, stan na październik 2026.
Czym są webhooki w Gemini API i od kiedy są dostępne?
Webhook w Gemini API to powiadomienie push. Zamiast odpytywać serwer w pętli, aplikacja rejestruje adres, na który Google wysyła żądanie HTTP POST po zakończeniu pracy asynchronicznej [1][2]. Funkcję ogłoszono 4 maja 2026 roku pod nazwą Webhooks in Gemini API [1]. Polling nadal działa i nie został wycofany [2][3]. Webhooki należą do szerszego ekosystemu Gemini, który obejmuje także modele, aplikację i plany subskrypcyjne; pełny opis znajdziesz na stronie huba Gemini.
Przed premierą dokumentacja pokazywała ręczne sprawdzanie operacji w pętli, między innymi przy generowaniu wideo Veo [4]. Webhook zamienia to oczekiwanie na jedno zdarzenie. Zakres jest jednak węższy, niż sugeruje nazwa: opis dotyczy Gemini Developer API, a nie każdego produktu Google [2].
Do jakich zadań webhooki mają zastosowanie?
Webhooki obsługują Batch API, asynchroniczne Interactions oraz generowanie wideo, w tym operacje Veo [2][4]. Zwykłe, synchroniczne wywołanie generateContent nie jest ich scenariuszem, bo odpowiedź wraca w tym samym żądaniu [2][3]. Webhook ma sens tam, gdzie praca trwa dłużej niż kilka sekund i nie chcesz trzymać otwartego połączenia.
Trzy warunki muszą być spełnione naraz: zadanie jest asynchroniczne, masz publicznie dostępny endpoint i potrafisz obsłużyć powtórzone dostawy tego samego zdarzenia [1][2]. Jeśli którykolwiek nie zachodzi, prostszy pozostaje polling albo Batch API bez powiadomień.
Jak skonfigurować webhook: tryb statyczny i dynamiczny?
Dokumentacja opisuje dwa tryby [2]. Statyczny to webhook projektowy, rejestrowany przez WebhookService i wspólny dla zadań w projekcie. Dynamiczny pozwala podać adres przy konkretnym zadaniu i dołączyć user_metadata, które wraca w powiadomieniu [2].
Endpoint musi odpowiedzieć kodem 2xx szybko, a cięższe przetwarzanie wykonać asynchronicznie [2]. Odpowiedź wysłana po długim czasie jest traktowana jak problem z dostawą, nie jak sukces. Warto rozdzielić odbiór żądania od właściwej pracy: przyjąć, zapisać i przetworzyć w tle.
Co zawiera powiadomienie i jak pobrać wynik?
Powiadomienie jest lekkie. Zawiera status, identyfikator i wskaźnik do rezultatu, na przykład output_file_uri; sam wynik trzeba pobrać osobnym żądaniem [5]. Każde żądanie niesie nagłówki webhook-id, webhook-timestamp i webhook-signature [2].
Dostawa jest typu at-least-once. Google ponawia próby z wykładniczym backoffem przez maksymalnie 24 godziny, więc ten sam webhook-id może dotrzeć więcej niż raz [1][2]. Odbiorca powinien deduplikować zdarzenia po identyfikatorze, a nie zakładać dokładnie jednej dostawy.
Jak zabezpieczyć endpoint webhooka?
Podpis zależy od trybu. Webhooki statyczne używają sekretu i HMAC, dynamiczne podpisów opartych na JWKS i JWT [2][5]. Weryfikacja podpisu jest obowiązkowa: bez niej każdy może wysłać fałszywe zakończenie zadania.
Drugi element to czas. Dokumentacja zaleca odrzucanie żądań starszych niż 5 minut, co ogranicza skutki przechwycenia i powtórzenia [2]. Trzeci to idempotencja po webhook-id [1]. Te trzy zasady kosztują kilka linii kodu i zamykają najczęstsze błędy.
Webhooki, polling i Batch API — co wybrać?
| Kryterium | Polling | Webhooki | Batch API |
|---|---|---|---|
| Sposób poznania wyniku | pętla operations.get() do zakończenia [4] | żądanie POST po zakończeniu [1] | powiadomienie o zakończeniu partii [2][6] |
| Ruch statusowy | rośnie z liczbą zapytań | jedno zdarzenie na zadanie [2] | brak pętli statusowej [2] |
| Koszt pracy modelu | według cennika [7] | według cennika, bez zmian [7] | 50% standardowej ceny [6] |
| Publiczny endpoint | niepotrzebny | wymagany [2] | wymagany, gdy odbiór przez webhook [2] |
Polling zostaje dla prostych przypadków i środowisk bez dostępu z internetu. Webhook wybierasz, gdy zależy Ci na czasie reakcji i masz gdzie odebrać żądanie. Batch API opłaca się przy dużych partiach, niezależnie od tego, czy odbierasz wynik webhookiem, czy sprawdzasz go później.
Czy webhooki obniżają koszt korzystania z Gemini API?
Webhook zmienia sposób powiadomienia, a nie sposób rozliczenia modelu [2][7]. Praca modelu nadal jest liczona według cennika tokenów. Realną obniżkę daje Batch API: obecnie kosztuje 50% standardowej ceny interaktywnej [6].
Przykład cen oficjalnych, stan na październik 2026: Gemini 4 Argon kosztuje 2 USD za 1 mln tokenów wejścia i 10 USD za 1 mln tokenów wyjścia do 30 listopada 2026 roku, a od 1 grudnia 2026 roku odpowiednio 4 USD i 20 USD [8]. To ceny deweloperskie podane przez Google; przed zakupem sprawdź aktualną stronę cennika [7].
Czy webhooki działają w Vertex AI?
Nie ma na to potwierdzenia. Dokumentacja webhooków dotyczy Gemini Developer API [2]. W forum deweloperskim zgłoszono, że webhooks.create zwraca błąd 404 w trybie Vertex AI [9]. Jeśli pracujesz na Vertex AI, traktuj webhooki jako funkcję niepotwierdzoną i sprawdź dostępność we własnym projekcie.
Kiedy webhooki nie są dobrym wyborem?
Trzy przypadki. Pierwszy: brak publicznego endpointu, na przykład aplikacja działa wyłącznie w sieci wewnętrznej. Drugi: praca synchroniczna, gdzie webhooki nie mają zastosowania [2]. Trzeci: zadania, w których liczy się każda sekunda i wolisz strumień odpowiedzi niż powiadomienie o końcu.
W pierwszym przypadku zostaje polling albo Batch API. W drugim wystarczy zwykłe wywołanie modelu. W trzecim webhook nadal pomaga, ale nie zastępuje transmisji wyniku w trakcie pracy. Warto porównać to z tym, jak inne modele rozliczają partie — na przykład w tekście o Gemini 3.5 Flash kontra konkurencja widać, że cennik bywa ważniejszy od samej funkcji. Jeśli budujesz aplikację na API, zajrzyj też do materiału o Google AI Studio i publikacji w Play Store oraz o tym, co Gemini 3.5 zmienia w firmach.
Najczęstsze pytania
Czy webhooki w Gemini API zastępują polling?
Nie zastępują go w całości. Webhooki eliminują pętlę statusową dla obsługiwanych operacji asynchronicznych, ale polling nadal działa i nie został wycofany [2][3]. Nie dotyczą też zwykłego, synchronicznego generateContent [2]. Wybór zależy od typu zadania, nie od daty premiery funkcji.
Czy webhooki w Gemini API są darmowe?
Samo powiadomienie nie jest osobną pozycją w cenniku, ale nie oznacza darmowej pracy modelu [2][7]. Rozliczane są tokeny wejściowe, wyjściowe i zadania asynchroniczne. Tańszą opcją dla dużych partii pozostaje Batch API, wyceniane na 50% standardowej ceny [6].
Ile kosztuje korzystanie z Gemini API?
Zależy od modelu i wolumenu. Gemini 4 Argon kosztuje 2 USD za 1 mln tokenów wejścia i 10 USD za 1 mln tokenów wyjścia do 30 listopada 2026 roku [8]. Cennik deweloperski opisuje też inne modele i warunki [7]. Ceny podane są w USD, więc do kosztu dochodzi przeliczenie na złote.
Czy webhook dotrze dokładnie raz?
Nie. Google deklaruje dostawę at-least-once i ponawia próby przez maksymalnie 24 godziny [1][2]. Ten sam webhook-id może pojawić się dwa razy, dlatego odbiorca musi deduplikować zdarzenia i zapisywać stan po identyfikatorze.
Czy webhooki działają w Vertex AI?
Brak potwierdzenia w dokumentacji, która opisuje Gemini Developer API [2]. Na forum deweloperskim zgłoszono błąd 404 przy webhooks.create w trybie Vertex AI [9]. Przed wdrożeniem sprawdź to we własnym projekcie.
Źródła
- Reduce friction and latency for long-running jobs with Webhooks in Gemini API (Google, 2026)
- Webhooks | Gemini API | Google AI for Developers (Google, 2026)
- Google Gemini API now supports event-driven webhooks — no more polling for batch jobs (Simon Carter, 2026)
- Generate videos with Veo 3.1 in Gemini API (Google, 2026)
- Google Adds Event-Driven Webhooks to the Gemini API, Eliminating the Need for Polling in Long-Running AI Jobs (MarkTechPost, 2026)
- Batch API | Gemini API | Google AI for Developers (Google, 2026)
- Gemini Developer API pricing | Gemini API | Google AI for Developers (Google, 2026)
- Gemini 4 Argon: Built to solve your hardest problems (Google, 2026)
- Are Webhooks API supported for Vertex AI batch jobs? (Google AI Developers Forum, 2026)