Gemini API now pings your server when batch jobs finish, ending polling

Google added event-driven webhooks to the Gemini API on May 4, 2026, according to its developer changelog. They are meant to replace polling for the Batch API and other long-running operations. The linked documentation labels the feature a preview.

Three kinds of jobs can now call your server

The changelog entry is a single line: Google says it launched webhook support to replace polling workflows for the Batch API and long-running operations. The details sit in the webhooks documentation, which now lives under aistudio.google.com after a redirect from ai.google.dev.

According to that page, webhooks cover Batch jobs, Interactions and video generation. The documented events are:

• Batch: batch.succeeded, batch.cancelled, batch.expired and batch.failed
• Interactions: interaction.requires_action, interaction.completed, interaction.failed and interaction.cancelled
• Video: video.generated

Developers can register in two ways. Static webhooks are project-level endpoints managed through a WebhookService API (create, get, list, update, delete and rotate the signing secret), and they fire for any matching event. The signing secret is shown only once at creation. Dynamic webhooks are set per request by adding a webhook_config with target URIs and optional user_metadata; the request must also set background to true.

Thin payloads, signed requests and a 24 hour retry window

The payloads are deliberately small. Each carries the event type, a version, a timestamp and a data object with the job ID and, where relevant, an output file URI or error details. The results themselves are not included, so a receiving server still has to fetch them.

Security follows two paths. Static webhooks use the Standard Webhooks specification, with webhook-id, webhook-timestamp and webhook-signature headers checked against the signing secret. Dynamic webhooks carry a signed JWT verified with RS256 public keys from a JWKS endpoint. The documentation tells developers to reject payloads older than 5 minutes.

Delivery is at-least-once. Endpoints are expected to answer with a 2xx status within a few seconds, and failed deliveries are retried with exponential backoff for 24 hours. Because duplicates are possible, Google advises using the webhook-id header to deduplicate and processing events after acknowledging them.

What the documentation leaves open

The page does not mention pricing, rate limits, payload size limits or endpoint quotas, and it gives no date for general availability. Anyone planning production use should treat it as a preview and check the current documentation. The changelog entry also does not say whether webhooks are available in every region.

The practical change is for teams running large batch jobs or long agent runs. Until now the pattern was to call GET /operations on a timer; a webhook turns that into a single inbound request, which saves wasted calls and removes the need for a scheduler that keeps checking. The trade-off is that the developer now has to expose a public HTTPS endpoint and handle verification and duplicates.

Part of a busy week for the Gemini API changelog

The track record is one of frequent, incremental platform changes. The changelog lists a File Search update on May 5 that adds multimodal search using the gemini-embedding-2 model, a notice on May 6 of a breaking Interactions API schema change that becomes the default on May 26, and the general availability of Gemini 3.1 Flash-Lite on May 7.

Google has kept building out the developer side since. Our earlier coverage covered a Gemini API command line tool built for agents and scripts and the move of Gemini text-to-speech models out of preview. Webhooks fit the same direction: tooling for unattended jobs, where no person is watching a screen waiting for a result.

The interaction events matter most for that direction. An interaction.requires_action event lets an agent run in the background and call back when it needs input, rather than holding a connection open or being polled. The documentation does not say how long such a run may last, so the practical ceiling is not established.