Gemini API Webhooks Signature Verifier
Verify a Gemini API webhook delivery before your handler updates a batch job, video generation, or agent workflow. This tool checks the Standard Webhooks HMAC format locally in the browser: webhook-id, webhook-timestamp, webhook-signature, and the exact raw request body.
Verify a Gemini webhook signature
HMAC verification runs locally. Attempt logs only store payload length, payload hash, status, and latency.
Ready to verify
Paste the Gemini webhook headers and raw body, then verify.
Verify before side effects
Check authenticity before marking a long-running Gemini job complete or starting downstream work.
Keep secrets local
HMAC verification runs in the browser. Logs store length, hash, status, and latency only.
Plan for retries
Gemini webhook delivery is event driven, so handlers should be idempotent and retry-safe.
Polling vs Gemini API Webhooks
| Decision point | Polling | Webhooks |
|---|---|---|
| Long-running jobs | Client repeatedly asks whether the job is done. | Gemini calls your endpoint when the event is ready. |
| Latency | Completion can sit idle until the next poll interval. | Completion can trigger downstream work immediately. |
| Reliability | Caller owns scheduling, backoff, and timeout behavior. | Receiver owns verification, idempotency, and 2xx acknowledgement. |
| Security | API key stays with the polling worker. | Receiver must verify signature and timestamp before processing. |
Production handler checklist
- Read the raw request body before any JSON parser changes it.
- Reject missing webhook-id, webhook-timestamp, or webhook-signature headers.
- Verify HMAC signatures in constant time and allow old keys during rotation.
- Reject timestamps outside your replay tolerance window.
- Use webhook-id as an idempotency key so retries do not double-process the same job.
- Return a 2xx only after the event is safely accepted or queued.
What this page does not do
Gemini also supports per-request webhook overrides secured through JWKS. That path needs asymmetric signature verification and a trusted public-key allow list. This first tool intentionally covers the project-level HMAC path because it is the fastest implementation most teams need for initial long-running job callbacks.
FAQ
What headers do Gemini API Webhooks use?
Google says Gemini API Webhooks follow the Standard Webhooks specification and sign deliveries with webhook-id, webhook-timestamp, and webhook-signature headers.
What does this verifier check?
It checks the HMAC-SHA256 Standard Webhooks signature over webhook-id.webhook-timestamp.rawPayload, including timestamp tolerance and multiple v1 signatures for key rotation.
Does this tool support JWKS webhook overrides?
Not yet. This first validation tool focuses on project-level HMAC webhooks. Gemini per-request overrides secured by JWKS need asymmetric verification and a trusted public-key list.
Why does reformatting JSON break webhook verification?
The signature is calculated over the exact raw body. Adding spaces, changing field order, or parsing and serializing JSON again can change the bytes and invalidate the signature.