Gemini API Webhooks Replace Polling for Long-Running AI Jobs
Use Gemini API's new event-driven webhooks to get instant push notifications on batch jobs, agent interactions, and video generation completion, cutting latency and API costs from constant GET /operations polling.
Switch to Push Notifications to Cut Latency and Costs
Polling GET /operations wastes quota and delays detection of job completion in long-running Gemini tasks like batch prompt processing (thousands overnight), Deep Research agents, or video generation (minutes to hours). Webhooks push HTTP POST payloads to your endpoint instantly on finish, using thin payloads with pointers like output_file_uri (e.g., gs://my-bucket/results.jsonl for batches) or video_uri for videos. This delivers real-time updates without looping requests, ideal for agentic workflows and high-volume pipelines.
At-least-once delivery retries up to 24 hours with exponential backoff; deduplicate via webhook-id. Respond with 2xx immediately after signature verification, queuing heavy processing to avoid triggering retries.
Static vs Dynamic Webhooks for Flexible Routing
Static webhooks register a project-level endpoint once via WebhookService API for global events like Slack alerts or DB syncs. Dynamic webhooks override per-request with webhook_config payload, routing specific jobs (e.g., agent queues) and attaching user_metadata like {"job_group": "nightly-eval", "priority": "high"} for downstream fan-out without extra tracking.
Event catalog: Batch (batch.succeeded, batch.cancelled, batch.expired, batch.failed, note batch.completed in some docs); Interactions API (interaction.requires_action for pending function calls, interaction.completed, etc.); Video (video.generated with file_id, video_uri). Branch handlers on event type to fetch results.
Secure with HMAC/JWKS and Replay Protection
Adheres to Standard Webhooks spec: Verify webhook-signature, webhook-id, webhook-timestamp headers. Reject payloads >5 minutes old to block replays.
Static: HMAC with one-time shared secret (store in env vars; rotate with REVOKE_PREVIOUS_SECRETS_AFTER_H24 for 24h grace). Dynamic: JWT RS256 signatures verified against Google's JWKS at https://generativelanguage.googleapis.com/.well-known/jwks.json—no shared secrets needed.
Trade-offs: Thin payloads minimize bandwidth but require follow-up fetches; at-least-once risks duplicates (handle idempotency); dynamic suits per-job flexibility but needs request-level config.