Reduce friction and latency for long-running jobs with Webhooks in Gemini API

Today, we’re making it easier and more efficient to build complex, long-running applications using the Gemini API. We are introducing event-driven Webhooks, a push-based notification system that eliminates the need for inefficient polling.

As Gemini evolves with agentic workflows and high-volume processing — like deep research, long video generation, or handling thousands of prompts through the Batch API — operations can take minutes or even hours. Until now, developers had to rely on continuous polling (e.g., repeatedly calling

GET

operations) to check if a job was completed.

Now, the Gemini API can simply push a real-time HTTP POST payload to your server the moment a task finishes.

We’ve designed this system with reliability and security in mind. Our implementation strictly follows the Standard Webhooks specification. Every request is signed using

webhook-signature

webhook-id

, and

webhook-timestamp

headers, ensuring idempotency and preventing replay attacks. We also guarantee “at-least-once” delivery with automatic retries for up to 24 hours.

How it works

You can configure webhooks globally at the project level (secured via HMAC), or override them dynamically on a per-request basis to route specific jobs (secured via JWKS).

Here’s a quick example of how you can dynamically configure a webhook for a batch task using the Python SDK:

```python
# Example code snippet in Python SDK
from google.api_core import exceptions as api_exceptions

def create_webhook(client, project_id):
  try:
    response = client.create_webhook(
      parent=f"projects/{project_id}",
      webhook={
        "name": f"projects/{project_id}/webhooks/webhook-1",
        "url": "http://example.com/notify",
        "request_headers": [
          {"key": "X-Signature", "value": "sha256=abc123"}
        ],
        "status_codes_to_retry_on": [408, 500],
      }
    )
    return response
  except api_exceptions.AlreadyExists:
    print("Webhook already exists.")
```

Get started today

Read the guide: Check out the Webhooks documentation to explore the full event catalog and learn how to secure your endpoints.
Hands-on practice: We’ve prepared a comprehensive Cookbook to help you build an end-to-end integration with webhooks.

Key Takeaways

Webhooks simplify the process of checking job completion by eliminating the need for continuous polling.
The system is designed to be reliable and secure, with features like automatic retries and HMAC/JSON Web Key Set (JWKS) security.
You can configure webhooks globally or on a per-request basis using the Gemini API’s Python SDK.

Originally published at blog.google. Curated by AI Maestro.

Stay ahead of AI. Get the most important stories delivered to your inbox — no spam, no noise.

Reduce friction and latency for long-running jobs with Webhooks in Gemini API