이 문서는 Gemini API에서 비동기식 또는 장기 실행 작업(LRO) 완료 시 서버에 실시간 알림을 푸시하는 웹훅(Webhook) 기능에 대해 상세히 설명합니다. 웹훅은 상태 업데이트를 위한 API 폴링을 불필요하게 하여 지연 시간과 오버헤드를 줄입니다.

작동 방식 및 웹훅 유형:
Gemini API는 이벤트 트리거 시 리스너 URL에 HTTP POST 요청을 전송하여 작동합니다. 웹훅은 크게 두 가지 유형으로 나뉩니다.

1. 정적 웹훅 (Static Webhooks): 프로젝트 수준에서 구성되는 엔드포인트로, 대칭 보안 비밀(symmetric security secret)을 사용하여 페이로드의 무결성을 확인합니다. 이는 전역적인 통합(예: Slack 알림, 데이터베이스 동기화)에 적합합니다.
   • 생성 및 관리: webhooks.create 메서드를 통해 웹훅을 생성하며, 이때 발급되는 new_signing_secret은 서명 확인에 필수적이므로 안전하게 저장해야 합니다. webhooks.get, webhooks.list, webhooks.update, webhooks.delete 메서드를 사용하여 웹훅을 조회, 나열, 업데이트, 삭제할 수 있습니다.
   • 서명 보안 비밀 순환 (Signing Secret Rotation): webhooks.rotate_signing_secret 메서드를 통해 보안 비밀을 순환할 수 있으며, 이전 보안 비밀의 취소 시점을 revocation_behavior 파라미터로 설정할 수 있습니다(예: REVOKE_PREVIOUS_SECRETS_AFTER_H24). 새로운 보안 비밀은 한 번만 반환되므로 즉시 저장해야 합니다.
   • 서버에서의 요청 처리: Gemini API는 구독된 이벤트 발생 시 웹훅 URI로 HTTP POST 요청을 전송합니다. 리스너 엔드포인트는 몇 초 이내에 2xx 상태 코드로 응답해야 하며, 실패 시 지수 백오프(exponential backoff)를 사용하여 24시간 동안 재시도합니다.
     • 페이로드 확인: 수신된 요청은 Webhook-Signature, Webhook-Timestamp, Webhook-Id 헤더를 포함하며, 미리 저장된 대칭 SIGNING_SECRET을 사용하여 페이로드의 서명을 검증해야 합니다. 이 과정은 standardwebhooks 라이브러리를 통해 예시로 제공됩니다.
     • 페이로드 구조: 웹훅은 대역폭 효율성을 위해 "씬 페이로드 모델(thin payload model)"을 사용하며, 원시 출력 파일 대신 상태 세부 정보와 결과 포인터(URI)가 포함된 스냅샷을 전송합니다. 페이로드는 type, version, timestamp, data 필드를 포함합니다. data 필드에는 이벤트 유형에 따라 id, output_file_uri, error_code, error_message 등의 항목이 포함됩니다. 예를 들어, batch.succeeded 이벤트는 id와 output_file_uri를 제공합니다.

2. 동적 웹훅 (Dynamic Webhooks): 특정 작업 호출의 구성 페이로드에서 웹훅 URL을 전달하는 요청 수준 재정의(request-level override)입니다. 에이전트 오케스트레이션 큐와 같이 특정 작업을 전용 엔드포인트로 라우팅하는 데 적합합니다.
   • 주요 차이점: 대칭 보안 비밀 대신 비대칭 공개 키 JWKS(JSON Web Key Set) 서명을 활용합니다.
   • 요청 제출: 비동기식 작업을 트리거할 때(예: batches.create), 요청의 config 내에 webhook_config 객체를 추가하여 동적 웹훅 URI와 선택적 user_metadata를 지정합니다.
   • 서명 확인 (JWKS): 수신된 동적 웹훅 요청의 Webhook-Signature 헤더는 JSON 웹 토큰(JWT)을 포함합니다. 리스너는 JWT에서 kid(Key ID)를 추출하고, Google의 공개 인증서 엔드포인트(https://generativelanguage.googleapis.com/.well-known/jwks.json)에서 해당 공개 키를 가져와 서명을 확인해야 합니다. 서명은 RS256 알고리즘과 구성된 audience를 사용하여 검증됩니다.

권장사항:

• 엄격한 재생 공격 방지: 모든 요청에 포함된 webhook-timestamp 헤더를 확인하여 5분보다 오래된 페이로드는 거부해야 합니다.
• 비동기식 처리: 유효한 서명이 감지되면 즉시 2xx OK로 응답하고, 내부적으로 파싱 작업을 대기열에 추가하여 리스너의 대기 시간을 줄여야 합니다.
• 중복 삭제 처리 (Deduplication): 표준 웹훅은 "최소 한 번(at least once)" 전송을 보장하므로, 일관된 webhook-id 헤더를 사용하여 중복 요청을 처리해야 합니다.