This paper details the implementation and usage of webhooks within the Gemini API, designed to provide real-time, asynchronous notifications for long-running operations (LROs), thereby reducing the latency and overhead associated with traditional polling mechanisms. The system supports two primary types of webhooks: Static Webhooks and Dynamic Webhooks, each suited for different use cases and employing distinct security models.

Static Webhooks are project-level configurations, managed through the Gemini WebhookService API, ideal for global integrations like notifying Slack or synchronizing databases. Their core methodology revolves around symmetric key cryptography for payload verification. Upon creation via SDKs (Python, JavaScript) or the REST API (POST /v1/webhooks), a unique new_signing_secret is returned *only once*. This secret is critical for server-side verification of incoming webhook requests. The server must securely store this secret and use it to validate the Webhook-Signature header against the received payload, typically leveraging libraries like standardwebhooks as demonstrated. Management operations include retrieving, listing, updating (e.g., $PATCH /v1/webhooks/<id>$ to modify subscribed events or URI), and deleting static webhooks. A crucial feature is the ability to rotate the signing secret ($POST /v1/webhooks/<id>/rotate_secret$), with options for immediate or delayed (24-hour grace period) revocation of the previous secret. When an event triggers a static webhook, the configured URI receives an HTTP POST request, which the listening server must acknowledge with a 2xx status code within seconds to prevent the Gemini API from initiating exponential backoff retries for up to 24 hours. Verification involves extracting the raw request body and headers, then using the stored SIGNING_SECRET to validate the Webhook-Signature header, ensuring payload integrity and authenticity.

Dynamic Webhooks offer request-level overrides, enabling a specific webhook endpoint to be bound to the configuration of a particular asynchronous operation call (e.g., batches.create with a webhook_config payload). This is particularly useful for agent orchestration queues where different operations might require notifications at distinct endpoints. The key distinction in security methodology for dynamic webhooks is the use of asymmetric public key JWKS (JSON Web Key Set) signatures, rather than shared secrets. When an event related to a dynamically configured operation occurs, the Gemini API sends a JSON Web Token (JWT) in the Webhook-Signature header. The receiving server must then extract the kid (key ID) from the JWT's header, fetch the corresponding public key from Google's official JWKS endpoint (https://generativelanguage.googleapis.com/.well-known/jwks.json), and then verify the JWT's signature using this public key and a specified audience (e.g., your-configured-audience).

Webhook Payload Structure and Event Catalog:
Both static and dynamic webhooks transmit a "thin payload" to conserve bandwidth, containing status details and pointers rather than raw output files. The common payload format is:

The data field varies based on the type of event. The documented event catalog includes batch.succeeded, batch.cancelled, batch.expired, batch.failed, interaction.requires_action, interaction.completed, interaction.failed, interaction.cancelled, and video.generated, each providing relevant data points like id, output_file_uri, error_code, or error_message.

Recommended Practices:
To ensure robust and scalable operations, the paper advises:

1. Strict Replay Protection: Always verify the webhook-timestamp header and reject payloads older than 5 minutes to mitigate replay attacks.
2. Asynchronous Processing: Respond with a 2xx OK immediately upon successful signature verification and queue payload parsing internally to avoid listener latency and retransmission cycles.
3. Idempotency (Deduplication): Handle potential duplicate deliveries, as webhooks guarantee "at least once" delivery. Use the consistent webhook-id header to identify and process unique events.