최근 복잡한 에이전트 기반 애플리케이션을 개발하는 과정에서 작업 완료 여부를 확인하기 위해 수 분에서 수 시간 동안 반복적으로 상태를 조회해야 하는 비효율이 발생하고 있다. 특히 긴 영상을 생성하거나 대규모 데이터를 처리하는 작업에서 이러한 폴링(주기적으로 서버에 상태를 묻는 방식)은 네트워크 자원과 연산 비용을 불필요하게 소모하는 주된 원인으로 지목된다.

Gemini API의 이벤트 기반 웹훅 도입

Google은 Gemini API를 활용한 에이전트 워크플로우와 대용량 처리를 효율화하기 위해 이벤트 기반 웹훅(특정 사건 발생 시 서버로 데이터를 밀어주는 방식)을 도입했다. 이번 업데이트를 통해 작업이 완료되는 즉시 HTTP POST 페이로드를 개발자의 서버로 직접 전송하는 방식이 가능해졌다. 이는 기존의 비효율적인 폴링 방식을 대체하며, Deep Research(심층 연구 수행 도구)나 Batch API(대량의 요청을 한 번에 처리하는 도구)와 같이 시간이 오래 걸리는 작업에서 특히 유용하다. 보안 측면에서는 표준 웹훅 규격을 엄격히 준수하며, 모든 요청에 서명(webhook-signature), 식별자(webhook-id), 타임스탬프(webhook-timestamp) 헤더를 포함해 재전송 공격을 방지한다. 또한 작업 실패 시 최대 24시간 동안 자동 재시도를 수행하여 최소 1회 이상의 데이터 전달을 보장한다.

기존 폴링 방식과의 차이점

예전에는 작업이 완료되었는지 확인하기 위해 개발자가 직접 GET 요청을 반복적으로 보내야 했다. 반면 이제는 서버가 작업 완료 시점을 스스로 인지하고 능동적으로 알림을 보내는 구조로 변경되었다. 설정 방식 또한 유연해졌다. 프로젝트 단위로 전역 웹훅을 설정(HMAC 방식의 보안 적용)할 수 있을 뿐만 아니라, 요청별로 웹훅을 동적으로 재정의하여 특정 작업만 별도의 경로로 라우팅하는 것도 가능하다(JWKS 방식의 보안 적용). 다음은 Python SDK를 사용하여 배치 작업에 웹훅을 동적으로 설정하는 예시 코드다.

python

Python SDK를 이용한 동적 웹훅 설정 예시

import google.generativeai as genai

배치 작업 생성 시 웹훅 엔드포인트 지정

operation = genai.create_batch_job(

model="gemini-1.5-flash",

requests=[...],

webhook_config={

"endpoint": "https://your-server.com/webhook",

"secret": "your-hmac-secret"

}

)

개발자가 바로 체감하는 변화는 작업 대기 시간의 단축과 서버 부하의 감소다. 실시간 알림 체계가 구축됨에 따라 에이전트가 다음 단계를 수행하기 위해 대기하는 시간이 줄어들고, 전체 파이프라인의 응답성이 향상된다. 이번 기능은 Gemini API를 사용하는 모든 개발자에게 즉시 제공되며, 상세한 구현 방법은 공식 문서에서 확인할 수 있다.