How to Implement Event-Driven Webhooks in the Gemini API

Google’s new event-driven Webhooks for the Gemini API let you eliminate constant polling for high-latency operations. You can now receive automatic HTTP callbacks for tasks running through the Batch API, Deep Research agents, and Veo 3.1 video generation. This removes the compute overhead of repeatedly calling GET /operations and simplifies your asynchronous infrastructure.

This guide details how to configure project-level and request-level webhook routing, verify signatures using the Standard Webhooks specification, and handle automatic retries.

Webhook Architecture and Delivery Guarantees

The Gemini API webhooks system provides “at-least-once” delivery for all registered events. When a job changes state, the API constructs an event payload and sends an HTTP POST request to your specified endpoint.

Your receiving server must respond with a 2xx HTTP status code to acknowledge receipt. If your server is down, times out, or returns an error code, the Gemini API automatically retries the delivery. The retry queue uses exponential backoff and will attempt to deliver the payload for up to 24 hours before dropping the event. This extended retry window provides durability for long-running tasks like Deep Research Max agent runs, which can operate autonomously for hours.

Choosing Between Static and Dynamic Webhooks

Google provides two configuration modes for routing events. Your choice depends on whether you need global infrastructure synchronization or job-specific callback handling.

Configuration Mode	Scope	Setup Method	Security Standard	Best Use Case
Static Webhooks	Project-level	WebhookService API	HMAC	Global database syncing, alerting systems.
Dynamic Webhooks	Request-level	webhook_config payload	JWKS	Granular routing, ephemeral multi-tenant architecture.

Static Webhooks are registered once per Google Cloud project. Every event generated within that project is routed to the configured endpoint. This pattern works well when you centralize all AI event processing through a single message broker or use the Gemini Enterprise Agent Platform to manage fleet-wide operations.

Dynamic Webhooks allow you to override the routing destination on a per-request basis. When initiating a job, you pass a destination URL inside the webhook_config parameter of the API call. This isolates callback logic, allowing a single API key to serve isolated microservices or direct responses back to specific client sessions.

Verifying Webhook Signatures

The Gemini implementation adheres strictly to the Standard Webhooks specification. You must verify incoming requests to ensure they originated from Google and prevent replay attacks.

Every incoming request includes three mandatory HTTP headers:

• webhook-signature: The cryptographic signature of the payload.
• webhook-id: A unique identifier for the specific event delivery.
• webhook-timestamp: The exact time the payload was generated.

For static webhooks, verification relies on an HMAC shared secret generated when you register the endpoint. For dynamic webhooks, security relies on JSON Web Key Sets (JWKS). Because dynamic endpoints do not share a pre-established secret, your application must fetch Google’s public keys to verify the payload signature.

The official Gemini API webhooks documentation contains the exact language-specific SDK implementations for validating these headers.

Supported Event Types

The event catalog categorizes payloads by service. When a webhook arrives, the payload contains a specific event type string that dictates the structure of the attached data.

The initial rollout supports several critical triggers:

• batch.completed: Fired when a Bulk processing job finishes successfully, useful when you want to reduce LLM API costs in production by batching offline queries.
• batch.failed: Fired when a batch job encounters a terminal error.
• interaction.requires_action: Fired by the Interactions API when a multi-turn agent conversation pauses and requires a user decision or external tool execution.

Implementation Constraints

The webhook architecture enforces specific technical limits. You cannot configure webhooks for standard, synchronous inference endpoints; they are strictly designed for asynchronous jobs. Additionally, dynamic webhook URLs must be publicly accessible and serve over HTTPS. Local development requires tunneling software like ngrok or Cloudflare Tunnels to receive the callbacks.

When implementing your webhook listener, decouple the payload verification from the actual business logic. Acknowledge the webhook with a 200 OK immediately after validating the signature, then push the payload to a local background worker. This prevents timeouts if your processing logic takes longer than the API’s standard connection window.