Gemini API Webhooks, AI 에이전트 런타임이 됐다

Google이 2026년 5월 4일 Gemini API에 Event-Driven Webhooks를 추가했습니다. 표면적으로는 익숙한 개발자 기능입니다. 어떤 작업이 끝나면 서버가 직접 알려줍니다. 결제, 이메일, CI, 배포, 협업 도구에서는 이미 오래된 패턴입니다. 하지만 이번 발표가 흥미로운 이유는 webhook 자체가 새로워서가 아닙니다. Google이 이 기능을 Gemini API의 장기 실행 AI 작업에 붙였다는 점이 중요합니다.

공식 발표는 Deep Research, 긴 비디오 생성, Batch API로 수천 개 prompt를 처리하는 작업을 예로 듭니다. 이런 작업은 몇 초 안에 응답이 돌아오는 일반적인 LLM 호출과 다릅니다. 몇 분에서 몇 시간까지 걸릴 수 있고, 실패·취소·만료·사용자 개입 같은 중간 상태가 생깁니다. 그동안 개발자는 이런 작업을 처리하려면 GET /operations를 반복 호출하며 상태를 확인해야 했습니다. Google은 이제 Gemini API가 작업 완료 순간 개발자 서버로 HTTP POST payload를 push할 수 있다고 설명합니다.

이 변화는 작은 편의 기능처럼 보이지만, 실제로는 AI 앱의 운영 모델을 바꿉니다. AI 에이전트가 긴 작업을 수행할수록 애플리케이션은 "모델에게 질문하고 답을 받는 코드"가 아니라 "작업을 등록하고, 외부 이벤트를 기다리고, 결과 포인터를 처리하고, 실패를 재시도하는 시스템"에 가까워집니다. Gemini API Webhooks는 그 전환을 공식 API 표면에 올린 업데이트입니다.

폴링 루프의 끝이 아니라 작업 모델의 변화입니다

기존 방식은 단순합니다. 서버가 Batch 작업을 만들고, 몇 초 또는 몇 분마다 상태 조회 endpoint를 호출합니다. 완료됐으면 결과를 가져오고, 실패했으면 에러를 기록합니다. 작은 규모에서는 이 방식도 충분합니다. 하지만 AI 워크로드가 장기 실행 작업으로 이동하면 polling은 금방 비용이 됩니다.

첫째, 불필요한 요청이 늘어납니다. 작업이 40분 걸리는데 10초마다 조회하면 작업 하나에 상태 조회만 240번 발생합니다. 수천 개 batch 작업을 동시에 돌리면 상태 조회 트래픽이 실제 AI 작업보다 더 예측하기 어려운 운영 부하가 됩니다.

둘째, latency가 polling interval에 묶입니다. 60초마다 확인하는 시스템은 작업이 끝난 뒤 최대 60초를 더 기다릴 수 있습니다. 5초마다 확인하면 latency는 줄지만 요청 수가 늘어납니다. AI 제품에서 완료 알림, 후속 agent step, 사용자 알림, 데이터베이스 sync가 이 이벤트에 매달려 있다면 작은 지연도 workflow 전체를 느리게 만듭니다.

셋째, 상태 관리 코드가 분산됩니다. 각각의 worker가 알아서 polling하고, timeout과 retry를 각자 구현하고, 중복 결과를 각자 처리하기 시작하면 운영 계층이 빠르게 지저분해집니다. 모델 성능이 좋아져도 주변 orchestration이 불안하면 제품은 안정적으로 커지지 않습니다.

Gemini API Webhooks는 이 구조를 뒤집습니다. 작업을 만든 뒤 개발자 서버가 기다립니다. 이벤트가 발생하면 Gemini API가 push합니다. 개발자는 받은 이벤트를 검증하고 내부 queue에 넣은 뒤, 결과 포인터를 따라 다음 작업을 진행합니다. 이것은 AI API를 전통적인 event-driven architecture 안으로 끌어들이는 변화입니다.

Google이 강조한 것은 보안 헤더입니다

이번 발표에서 눈에 띄는 부분은 Google이 webhook을 단순 callback URL로만 설명하지 않았다는 점입니다. 공식 발표와 문서는 모두 Standard Webhooks 사양을 따르며, 모든 요청에 webhook-signature, webhook-id, webhook-timestamp 헤더를 붙인다고 설명합니다.

이 세 가지는 운영에서 각각 다른 역할을 합니다. webhook-signature는 payload가 실제 Gemini API에서 왔는지 확인하는 서명입니다. webhook-id는 같은 이벤트가 여러 번 도착했을 때 deduplication key로 쓸 수 있습니다. webhook-timestamp는 오래된 요청을 다시 보내는 replay attack을 막기 위한 시간 정보입니다. 공식 문서는 timestamp가 5분보다 오래된 payload를 거부하라고 권합니다.

이것은 특히 AI 작업에서 중요합니다. AI batch 작업의 결과는 단순 알림이 아니라 비용이 발생한 작업의 산출물이며, 경우에 따라 내부 문서, 고객 데이터, 코드 분석 결과, 영상 생성 output pointer를 포함합니다. webhook endpoint가 제대로 검증되지 않으면 공격자는 가짜 완료 이벤트를 보내 내부 workflow를 움직이게 만들 수 있습니다. 반대로 중복 이벤트 처리를 제대로 하지 않으면 같은 결과를 두 번 저장하거나, 같은 후속 작업을 여러 번 실행하거나, 사용자에게 중복 청구를 발생시킬 수 있습니다.

공식 문서는 static webhook과 dynamic webhook을 나눕니다. static webhook은 프로젝트 단위 endpoint를 등록하고 HMAC 기반 signing secret으로 검증합니다. dynamic webhook은 특정 요청 payload에 webhook URL을 넣어 작업별 endpoint로 라우팅할 수 있고, 비대칭 JWKS 서명을 사용합니다. 이 구분은 작은 기능 차이가 아니라 운영 조직의 선택지입니다. 전사 공통 pipeline은 static webhook으로 받고, 특정 agent run이나 고객별 작업은 dynamic webhook으로 분리할 수 있습니다.

지원 이벤트는 AI 앱의 실제 상태를 보여줍니다

Gemini API Webhooks 문서의 이벤트 카탈로그도 중요합니다. 단순히 completed 하나만 있는 것이 아닙니다. batch.succeeded, batch.cancelled, batch.expired, batch.failed가 있고, Interactions API에는 interaction.requires_action, interaction.completed, interaction.failed, interaction.cancelled이 있습니다. 비디오 생성에는 video.generated가 있습니다.

여기서 가장 흥미로운 이벤트는 interaction.requires_action입니다. 에이전트형 앱은 항상 자동으로 끝나지 않습니다. 함수 호출이 필요하거나, 사용자가 결정을 내려야 하거나, 외부 시스템의 권한 승인이 필요할 수 있습니다. Google이 이 상태를 webhook 이벤트로 둔 것은 Gemini API가 단순 모델 호출이 아니라 상태 있는 interaction runtime으로 확장되고 있음을 보여줍니다.

또 하나 중요한 점은 payload가 thin payload라는 것입니다. 공식 문서는 대역폭 혼잡을 피하기 위해 결과 전체를 webhook payload에 싣지 않고, 상태와 결과 pointer를 전달한다고 설명합니다. 예시 payload는 batch.succeeded 이벤트와 output_file_uri를 포함합니다. 즉 webhook은 결과를 운반하는 통로가 아니라, 결과를 가져오라고 알려주는 control plane에 가깝습니다.

이 설계는 합리적입니다. 긴 비디오 생성 결과나 대규모 batch output을 HTTP callback payload로 직접 보내면 endpoint timeout, 네트워크 실패, 재전송 비용이 커집니다. pointer를 보내고 결과는 별도 저장소에서 가져오게 하면 delivery는 가볍고, 후속 처리도 queue로 분리하기 쉽습니다. AI 인프라가 커질수록 결과 데이터 plane과 이벤트 control plane을 분리하는 방식이 중요해집니다.

장기 실행 AI 작업은 이제 백엔드 설계 문제입니다

개발자가 이번 업데이트에서 바로 얻는 이점은 명확합니다. polling worker를 줄이고, 작업 완료를 더 빠르게 감지하고, 실패한 delivery를 Gemini API의 재시도 메커니즘에 맡길 수 있습니다. 공식 문서는 webhook endpoint가 몇 초 안에 2xx를 반환해야 하며, 실패하면 exponential backoff로 최대 24시간 재시도한다고 설명합니다.

하지만 이 말은 다른 책임도 생긴다는 뜻입니다. endpoint는 이벤트를 받은 즉시 검증하고 내부 queue에 넣은 뒤 빠르게 응답해야 합니다. callback handler 안에서 결과 파일을 다운로드하고, 데이터베이스를 업데이트하고, 다음 agent를 호출하고, 사용자 알림까지 보내는 긴 작업을 모두 처리하면 delivery retry와 중복 처리 위험이 커집니다. webhook handler는 얇아야 합니다.

또한 at-least-once delivery는 "적어도 한 번 온다"는 뜻이지 "정확히 한 번만 온다"는 뜻이 아닙니다. 같은 이벤트가 두 번 올 수 있습니다. 그러므로 webhook-id나 이벤트의 resource id를 기준으로 멱등성을 설계해야 합니다. batch output을 저장할 때는 이미 처리한 job인지 확인해야 하고, 후속 agent step을 실행할 때도 같은 run을 두 번 시작하지 않게 해야 합니다.

이 지점에서 AI 앱은 전통적인 분산 시스템 문제와 만납니다. idempotency key, dead-letter queue, retry policy, rate limit, audit log, billing cap 같은 익숙한 단어들이 모델 성능만큼 중요해집니다. 에이전트가 더 오래 일할수록 "좋은 prompt"만으로는 충분하지 않습니다. 에이전트가 끝났는지, 실패했는지, 사용자의 개입이 필요한지, 결과를 어디서 가져와야 하는지, 같은 이벤트가 다시 왔을 때 어떻게 처리할지를 시스템이 알아야 합니다.

Gemini File Search와 함께 보면 방향이 더 선명합니다

흥미롭게도 Google은 다음 날인 2026년 5월 5일 Gemini API File Search의 멀티모달 확장도 발표했습니다. File Search는 이미지와 텍스트를 함께 처리하고, custom metadata filter와 page-level citations를 제공합니다. 이 두 발표를 나란히 보면 Google의 개발자 전략이 보입니다.

File Search는 AI 앱이 사용할 지식 계층을 관리형 서비스로 올립니다. Webhooks는 장기 실행 작업의 상태와 완료 이벤트를 관리형 이벤트로 올립니다. 하나는 retrieval plane이고, 다른 하나는 execution plane입니다. 둘 다 개발자가 직접 만들 수 있는 기능이지만, Google은 Gemini API 안으로 끌어들여 "모델 호출 주변의 인프라"를 제품화하고 있습니다.

이것은 AI 플랫폼 경쟁에서 중요한 방향입니다. 2024년과 2025년의 경쟁은 주로 모델 성능, context window, 토큰 가격, multimodal 품질에 집중됐습니다. 2026년의 경쟁은 점점 운영 계층으로 이동합니다. 누가 agent를 오래 실행하게 할 수 있는가, 누가 결과를 검증 가능하게 만들 수 있는가, 누가 비용과 상태를 관리하기 쉽게 만드는가가 실무 채택을 좌우합니다.

Gemini API Webhooks는 이 경쟁에서 Google이 "AI 작업은 오래 걸릴 수 있고, 오래 걸리는 작업은 이벤트로 운영해야 한다"는 전제를 명시한 기능입니다. 작은 API 업데이트처럼 보여도, AI 앱의 기본 구조를 바꾸는 신호로 읽을 수 있습니다.

커뮤니티 반응은 조용하지만 실무 쪽입니다

이번 발표는 대형 모델 릴리스처럼 큰 논쟁을 만들지는 않았습니다. Hacker News에서 뚜렷한 대형 토론은 확인하기 어려웠습니다. 대신 개발자 커뮤니티에서는 실제 연결 실습이 빠르게 나왔습니다. 예를 들어 일본 DevelopersIO는 AWS Lambda Function URL로 Gemini API Webhook을 받고, webhook-id, webhook-timestamp, webhook-signature 헤더를 확인하는 실습을 공개했습니다. 이런 반응은 hype보다 더 실무적입니다. webhook은 발표를 읽는 기능이 아니라 운영 환경에 붙여 보면서 신뢰성을 확인해야 하는 기능이기 때문입니다.

반면 Reddit의 Google Cloud와 Gemini API 커뮤니티에서는 최근 API key 노출과 Gemini 비용 폭증 사례가 반복적으로 올라오고 있습니다. 이것은 Gemini API Webhooks 자체의 결함을 말하는 것은 아닙니다. 하지만 장기 실행 AI 작업을 자동화할 때 비용 guardrail이 얼마나 중요한지 보여주는 배경입니다. webhook이 polling 비용을 줄여도, 잘못 노출된 API key나 무제한 batch 작업은 훨씬 큰 비용 문제를 만들 수 있습니다.

따라서 실무 팀은 이번 기능을 "편해졌다"로만 받아들이면 안 됩니다. webhook endpoint는 인증과 서명 검증을 해야 하고, Gemini API key는 최소 권한과 제한을 가져야 하며, Batch나 video generation 같은 고비용 작업에는 사용량 cap과 알림이 필요합니다. 이벤트 기반이 되면 자동화는 빨라집니다. 자동화가 빨라질수록 잘못된 요청도 더 빨리 비용으로 바뀝니다.

개발팀은 무엇을 바꿔야 하나

Gemini API를 이미 쓰고 있다면 가장 먼저 볼 곳은 장기 실행 작업입니다. Batch API로 평가 데이터셋을 돌리거나, Deep Research류 작업을 제품 안에 넣거나, video generation을 백그라운드에서 처리하는 팀이라면 polling worker를 webhook 기반으로 바꾸는 것이 자연스럽습니다.

권장 구조는 단순합니다. public webhook endpoint는 raw body를 보존한 채 서명을 검증합니다. timestamp가 너무 오래됐으면 거부합니다. 검증이 끝나면 이벤트 id와 resource id를 idempotency store에 기록하고, 내부 queue에 작업을 넣고, 즉시 2xx를 반환합니다. 실제 결과 다운로드, 데이터베이스 update, 사용자 알림, 후속 agent 호출은 worker가 처리합니다.

이때 결과 pointer를 신뢰하되, 결과 자체의 처리 상태는 별도로 기록해야 합니다. webhook이 batch.succeeded를 보냈다는 사실과 우리 시스템이 output file을 성공적으로 가져와 파싱했다는 사실은 다릅니다. 첫 번째는 외부 이벤트이고, 두 번째는 내부 처리 결과입니다. 이 둘을 같은 상태로 섞으면 장애 분석이 어려워집니다.

또한 dynamic webhook은 편리하지만 남용하면 endpoint 관리가 복잡해질 수 있습니다. 고객별 callback URL을 받는 제품이라면 SSRF, allowlist, domain verification, retry storm을 따로 고려해야 합니다. 단순 내부 파이프라인이라면 static webhook 하나로 시작하고, 내부 metadata로 라우팅하는 편이 더 안정적일 수 있습니다.

결론: 모델 API가 운영 API가 되고 있습니다

Gemini API Webhooks는 화려한 모델 발표가 아닙니다. benchmark 숫자도 없고, 새로운 reasoning 능력도 없습니다. 하지만 AI 제품을 실제로 운영하는 팀에게는 이런 업데이트가 더 오래 남습니다. 장기 실행 작업이 늘어날수록 모델 API는 단순 함수 호출이 아니라 운영 API가 됩니다.

Google은 이번 기능으로 Gemini API의 장기 실행 작업을 event-driven backend에 붙이기 쉽게 만들었습니다. 동시에 개발자에게 분명한 메시지를 보냈습니다. 에이전트형 AI 앱은 polling loop 위에서 오래 버티기 어렵습니다. 서명된 이벤트, thin payload, idempotency, retry, queue, audit log가 기본 구성요소가 됩니다.

개발자 관점에서 이번 업데이트의 핵심은 "polling을 안 해도 된다"가 아닙니다. 더 정확히는 "AI 작업을 상태 있는 workflow로 다루는 공식 경로가 생겼다"입니다. Gemini API가 File Search로 지식 계층을, Webhooks로 실행 이벤트 계층을 제공하기 시작했다면, 다음 경쟁은 모델 자체보다 누가 더 안정적인 agent runtime을 제공하는가로 옮겨갈 가능성이 큽니다.