구글, Gemini API에 이벤트 기반 Webhooks 도입… Standard Webhooks 사양·HMAC/JWKS 서명·최대 24시간 자동 재시도

구글이 Gemini API용 이벤트 기반 Webhooks를 도입한다고 발표했다. 기존의 비효율적인 폴링(polling)을 대체하는 푸시 기반 알림 시스템으로, 복잡하고 장기 실행되는 에이전틱 애플리케이션 개발을 더 쉽고 효율적으로 만든다.

Gemini가 Deep Research, 긴 영상 생성, Batch API를 통한 수천 개 프롬프트 처리 등 에이전틱 워크플로와 대용량 처리로 옮겨가면서 작업이 수 분에서 수 시간까지 걸리는 경우가 늘어났다. 지금까지 개발자는 GET 호출을 반복하는 방식의 지속적인 폴링에 의존해 작업 완료 여부를 확인해야 했다.

이번에 도입된 Webhooks는 작업이 완료되는 순간 Gemini API가 개발자 서버로 실시간 HTTP POST 페이로드를 직접 전송하도록 한다. 폴링 호출 없이 푸시만으로 작업 종료를 통지받을 수 있어 지연과 자원 낭비를 줄일 수 있다.

구글은 이 구현이 Standard Webhooks 사양을 엄격히 준수한다고 밝혔다. 모든 요청에는 webhook-signature, webhook-id, webhook-timestamp 세 개 헤더로 서명이 붙어 멱등성을 보장하고 재전송(replay) 공격을 차단한다.

전송 신뢰성 측면에서는 '최소 한 번(at-least-once)' 전달을 보장하며, 실패 시 최대 24시간 동안 자동 재시도한다.

구성 방식은 두 가지다. 프로젝트 단위로 전역 Webhook을 설정할 수 있으며 이때는 HMAC으로 보호된다. 또한 요청별로 특정 작업의 라우팅을 동적으로 오버라이드할 수도 있는데 이 경로는 JWKS로 보호된다.

구글은 사용 예시로 Python SDK를 통해 배치(batch) 작업에 동적으로 Webhook을 구성하는 방법을 함께 제시했다.

이 기능은 발표 시점부터 Gemini API를 사용하는 모든 개발자에게 제공된다. 구글은 전체 이벤트 카탈로그와 엔드포인트 보안 가이드를 다루는 Webhooks 문서, 그리고 종단 간 연동을 다루는 Cookbook을 함께 공개했다.