Gemini API의 Webhooks로 장기 작업의 마찰과 지연 줄이기

Gemini API가 장기 실행 작업을 위한 Webhooks를 도입했다. Deep Research, 긴 비디오 생성, Batch API로 수천 개 프롬프트를 처리하는 작업처럼 몇 분에서 몇 시간 걸리는 흐름에서, 계속 GET으로 상태를 확인하는 폴링 대신 완료 시점에 서버로 HTTP POST를 푸시한다.

신뢰성과 보안은 Standard Webhooks 사양을 따른다. webhook-signature, webhook-id, webhook-timestamp 헤더로 서명해 멱등성을 보장하고 재전송 공격을 막으며, 전달은 at-least-once 방식으로 최대 24시간 자동 재시도된다.

설정은 두 가지다.

• 프로젝트 전역 설정은 HMAC으로 보호한다.
• 요청별 오버라이드는 JWKS로 보호하며, 특정 작업을 다른 엔드포인트로 보낼 수 있다.

Python SDK 예시에서는 client.batches.create()에 model=gemini-3-flash-preview, webhook_config, user_metadata를 넣어 https://my-api.com/gemini-webhook-dynamic으로 알림을 보낸다. 기능은 지금 모든 Gemini API 개발자에게 제공되며, 문서와 Cookbook 노트북으로 바로 시작할 수 있다.