If you’ve ever built an AI production pipeline that runs long jobs-such as processing thousands of claims overnight, launching a deep search agent, or creating a long-form video-you’ve almost certainly dealt with the polling problem. Your code is in a loop, and it is launched GET Every few seconds he asks: “Is the job finished yet?” It’s wasteful, adds latency, and widely becomes a reliability headache. Google has just shipped a fix.
Google provided Event-driven webhooks For Gemini API – a push-based notification system that eliminates the need for passive polling. The feature is now available to all developers using the Gemini API and targets a key pain point in agent and high-volume AI workflows.
Why is polling so broadly collapsing?
To understand the problem, it’s helpful to know what a long run operation (LRO) is. Webhooks allow the Gemini API to send real-time notifications to your server when asynchronous or long-running operations are complete, replacing the need to poll the API for status updates and reducing latency and overhead.
Before webhooks, the only option was continuous polling, i.e. frequent connection GET /operations To check if the task has finished. As Gemini shifts toward proxy workflows and high-volume processing – such as deep searching, creating long-form videos, or processing thousands of claims via the Batch API – processes can take minutes or even hours. Polling for hours is expensive in both compute and API share, and introduces unnecessary delays between when a task is complete and when your application knows about it.
The solution is simple in theory: instead of asking your code “Are you done?” Recursively, the Gemini API calls your server the moment the task finishes, by pushing a real-time HTTP POST payload to your endpoint the moment the task completes.
Two configuration modes: static and dynamic
The Gemini API supports two ways to configure webhooks. Static webhooks are project-level endpoints configured using the WebhookService API and are suitable for global integrations such as Slack notification or database synchronization – they are registered once per project and triggered for any corresponding event. Dynamic webhooks are request-level overrides that pass the URL of the webhook into a file webhook_config Task-specific call payload, ideal for routing specific tasks to custom endpoints, for example in agent orchestration queues.
You can think of static webhooks as a standing instruction to your mail carrier: “Always deliver packages to the front desk.” Dynamic webhooks are a lot like saying, “For this one shipment, send it to my home address.” An additional advantage of dynamic webhooks is user_metadata field, which allows you to attach arbitrary key-value metadata to a task at submit time – e.g. {"job_group": "nightly-eval", "priority": "high"}. This metadata travels with the job notification and is especially useful when you need to distribute different job types to different processors without creating a separate tracking layer.
Security architecture: Standard Webhooks, HMAC, and JWKS
Security is where this implementation becomes technically interesting. Google’s implementation strictly adheres to the Webhooks standard. Every request is signed using webhook-signature, webhook-idand webhook-timestamp heads, ensuring incapacitation and preventing replay attacks.
For static webhooks, signing is done with HMAC (Hash-based Message Authentication Code) using a symmetric shared secret, which is provided once at creation time and must be stored securely in your environment variables – the API only returns this signing secret once and cannot be retrieved again. If you lose it, you have to rotate it. Rotation endpoint supports A revocation_behavior Parameter – specifically REVOKE_PREVIOUS_SECRETS_AFTER_H24which keeps the legacy secret valid for a 24-hour grace period so you can move production systems safely, or an immediate revocation option for incident response.
For dynamic webhooks, Google uses asymmetric JWKS (JSON Web Key Set) signatures instead of symmetric secrets. Dynamic webhook requests emit a JSON Web Token (JWT) signature, which the listener must extract and verify using Google’s public certificate endpoints at https://generativelanguage.googleapis.com/.well-known/jwks.json. RS256 algorithm is used for this verification.
This means that your server never trusts incoming requests blindly – every click on the webhook can be validated before acting on it. the webhook-timestamp The header is especially important: best practices call for always validating this timestamp and rejecting payloads older than five minutes to mitigate replay attacks.
Thin payloads and event catalog
One noteworthy architectural decision is the thin payload model. To avoid bandwidth congestion, Gemini webhooks provide a snapshot containing status details and indicators of the results, rather than the raw output file itself. The exact fields in that snapshot depend on the type of event.
For batch jobs, the completed notification holds the job id and output_file_uri To indicate your results – for example, a cloud storage path such as gs://my-bucket/results.jsonl. To generate video, video.generated The event offers a different set of fields: file_id and video_uri. Your server-side handler needs to branch on the event type before reading the payload data fields.
The complete event catalog covers three categories: Batch functions (batch.succeeded, batch.cancelled, batch.expired, batch.failed), API operations for interactions (interaction.requires_action, interaction.completed, interaction.failed, interaction.cancelled), and video creation (video.generated). For developers who write code: Official code samples in Google Docs are subscribed and handled batch.completed instead of batch.succeeded -Both appear throughout the documentation, so match whatever your implementation uses.
The Reactions API, for readers who aren’t familiar with it, is the Gemini API for asynchronous multi-turn agent conversations. the interaction.requires_action The event is particularly useful – it is triggered when a function call is pending and your application needs to step in and take action before the agent can continue.
Delivery guarantees and best practices
Google guarantees “at least once” delivery with automatic retries for up to 24 hours using exponential backoff. The “at least once” guarantee means that your endpoint may sometimes receive the same event more than once under high traffic conditions. Consistent webhook-id You must use header to deduplicate these. Your server should also respond with 2xx Status code as soon as the correct signature is detected and any heavier analysis is queued internally – prolonged listener hold times trigger a retry cycle, which is the opposite of what you want.
Key takeaways
- No more polling loops – Gemini API now pushes a signed HTTP POST to your server immediately after a long-running task (Batch API, Deep Search, Video Creation) is completed, eliminating the need to connect frequently
GET /operations. - Two web hook modes for different builds – Static webhooks handle global project-level integrations secured via HMAC; Dynamic webhooks are linked to individual work requests via JWKS signatures and support
user_metadataFor custom routing logic in agent coordination routes. - Security is built-in, not installed – Each notification is cryptographically signed according to the standard Webhooks specification used
webhook-signature,webhook-idandwebhook-timestampHeads. Reject and use payloads older than 5 minutes to prevent replay attackswebhook-idTo deduplicate deliveries at least once. - Thin payloads, not raw results – Webhook notifications carry status indicators, not output data. Return batch events
output_file_uri; Video events returnfile_idandvideo_uri. Always reply2xxInstantly and asynchronously processed – slow responses result in exponential backoff retries for up to 24 hours.
verify Technical details here. Also, feel free to follow us on twitter Don’t forget to join us 130k+ ml SubReddit And subscribe to Our newsletter. I am waiting! Are you on telegram? Now you can join us on Telegram too.
Do you need to partner with us to promote your GitHub Repo page, face hug page, product release, webinar, etc.? Contact us
