Receive and verify Google Gemini API webhooks. Use when setting up Gemini webhook handlers for batch jobs, video generation, or Interactions API function-calling LROs, debugging signature verification, or handling events like batch.succeeded, batch.failed, video.generated, or interaction.completed.
Receive and verify Google Gemini API webhooks. Use when setting up Gemini webhook handlers for batch jobs, video generation, or Interactions API function-calling LROs, debugging signature verification, or handling events like batch.succeeded, batch.failed, video.generated, or interaction.completed.
Handling batch.succeeded / batch.failed notifications for the Batch API
Handling video.generated notifications for the Veo/video generation API
Handling interaction.completed / interaction.requires_action events for the Interactions API
Replacing polling for long-running Gemini operations (LROs)
Verifying Standard Webhooks-format signatures from Google generativelanguage.googleapis.com
Essential Code (USE THIS)
Gemini webhooks follow the Standard Webhooks specification.
Each delivery includes three headers:
webhook-id — unique message id (use for idempotency)
webhook-timestamp — Unix seconds (reject if > 5 minutes old)
webhook-signature — one or more space-separated v1,<base64-hmac-sha256> entries over webhook-id.webhook-timestamp.body (multiple entries appear during secret rotation)
The signing secret is returned once when the webhook is created via the WebhookService API
and is base64-encoded, prefixed with whsec_.
Static webhooks (recommended default) — project-level endpoints registered via the
WebhookService API. Signed with a symmetric secret using Standard Webhooks
(HMAC-SHA256). All examples here use this mode.
Dynamic webhooks — per-job endpoint passed in the request webhook_config. Signed
asymmetrically with an RS256 JWT in the Webhook-Signature header; verify against
Google's JWKS at https://generativelanguage.googleapis.com/.well-known/jwks.json.
Useful for per-request routing via user_metadata. See
references/verification.md for the JWT verification flow.
Environment Variables
GEMINI_API_KEY=your-api-key # Your Gemini API key
GEMINI_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxx # Static webhook signing secret (whsec_-prefixed)
Local Development
# Tunnel localhost to a public URL Gemini can reach (no account required)
npx hookdeck-cli listen 3000 gemini --path /webhooks/gemini
We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
Handler sequence — Verify first, parse second, handle idempotently third
hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers