수천 개의 프롬프트를 처리하거나 긴 영상을 생성하는 AI 파이프라인을 운영하는 개발자라면 누구나 폴링(Polling, 주기적으로 상태를 확인하는 방식) 문제에 직면한다. 서버는 작업이 끝났는지 확인하기 위해 몇 초마다 GET 요청을 반복적으로 보낸다. 이는 불필요한 대역폭 낭비와 지연 시간을 유발하며, 대규모 시스템에서는 신뢰성을 떨어뜨리는 주된 원인이 된다. Google은 최근 Gemini API에 이벤트 기반 웹훅(Webhook, 특정 사건 발생 시 서버가 외부로 알림을 보내는 방식)을 도입하여 이 문제를 해결했다.

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

이번 업데이트로 Gemini API는 비동기 작업이나 장기 실행 작업(LRO, Long-Running Operation)이 완료되는 즉시 개발자의 서버로 HTTP POST 페이로드를 전송한다. 기존에는 GET /operations 엔드포인트를 통해 작업 상태를 계속 확인해야 했으나, 이제는 시스템이 스스로 완료 시점을 알린다. 정적 웹훅(Static Webhooks)은 프로젝트 단위의 엔드포인트로 슬랙 알림이나 데이터베이스 동기화와 같은 전역적인 작업에 적합하다. 반면 동적 웹훅(Dynamic Webhooks)은 개별 작업 요청 시 webhook_config 페이로드에 URL을 직접 지정할 수 있어, 에이전트 오케스트레이션 큐와 같이 특정 작업 경로를 분기해야 하는 상황에 유용하다. 특히 동적 웹훅은 user_metadata 필드를 통해 작업별로 고유한 키-값 데이터를 첨부할 수 있어 별도의 추적 레이어 없이도 하위 프로세서를 효율적으로 분기할 수 있다.

보안 및 데이터 검증 방식의 차이

예전에는 서버가 들어오는 요청을 무조건 신뢰하거나 자체적인 인증 로직을 복잡하게 구현해야 했다. 이제는 Standard Webhooks 사양을 준수하여 모든 요청에 서명 헤더가 포함된다. 정적 웹훅은 HMAC(Hash-based Message Authentication Code, 대칭키 기반의 메시지 인증 코드) 방식을 사용하며, 보안을 위해 최초 생성 시에만 제공되는 공유 비밀키를 환경 변수에 저장해야 한다. 비밀키 유출 시에는 REVOKE_PREVIOUS_SECRETS_AFTER_H24 설정을 통해 24시간 동안 기존 키를 유효하게 유지하며 안전하게 키를 교체할 수 있다. 동적 웹훅은 비대칭 공개키인 JWKS(JSON Web Key Set, 공개키를 모아놓은 집합) 방식을 사용한다. 개발자는 Google 공개 인증서 엔드포인트를 통해 RS256 알고리즘으로 요청의 유효성을 검증할 수 있다. 또한 5분 이상 지난 타임스탬프를 거부하는 방식으로 재전송 공격(Replay Attack)을 방지한다.

개발자가 체감하는 워크플로우 변화

결과적으로 개발자는 API 호출 효율성을 극대화하고 인프라 비용을 절감할 수 있게 되었다. Gemini API는 대역폭 혼잡을 피하기 위해 원본 데이터를 직접 보내지 않고, 작업 상태와 결과물의 위치를 가리키는 포인터 정보를 담은 얇은 페이로드를 전달한다. 예를 들어 배치 작업이 완료되면 결과가 저장된 Cloud Storage 경로(gs://my-bucket/results.jsonl)를 제공하며, 영상 생성 작업은 file_id와 video_uri를 반환한다. 지원되는 이벤트 카테고리는 배치 작업(batch.succeeded 등), Interactions API(다중 턴 에이전트 대화를 위한 API) 작업, 영상 생성 등 세 가지다. 개발자는 이벤트 유형에 따라 서버 측 핸들러를 분기하여 처리하면 된다. 이제 AI 파이프라인은 수동적인 확인 루프에서 벗어나, 데이터가 준비되는 즉시 반응하는 이벤트 기반 아키텍처로 완전히 전환되었다.