AI 워크플로는 겨우 돌아가기 시작했는데, 이제는 "끝났나?"를 확인하느라 돈과 엔지니어링 시간이 새고 있다면 그다음 고민은 기능 추가가 아니라 구조 변경입니다.
구글은 Gemini API에 이벤트 기반 웹훅을 추가했습니다. 이제 장시간 실행 작업이 끝났을 때 API가 개발자 서버로 직접 HTTP POST를 보내며, 반복 조회 폴링을 줄일 수 있습니다. 특히 Deep Research, 장시간 비디오 생성, 대량 배치 처리처럼 분 단위에서 시간 단위까지 걸리는 작업이 늘어나는 지금, 이 변화는 편의 기능이라기보다 아키텍처 선택지에 가깝습니다.12
먼저 판단할 것: 당신 제품에 웹훅이 정말 필요한가
모든 AI 제품이 웹훅으로 갈아탈 필요는 없습니다.
작업이 5~10초 안에 끝나고 사용자가 화면에서 바로 결과를 기다리는 구조라면, 단순 요청-응답이나 짧은 폴링이 더 낫습니다. 운영 포인트가 적고 디버깅도 쉽습니다. 반대로 작업이 수분 이상 걸리거나, 한 번에 수백~수천 건을 처리하거나, 완료 즉시 후속 액션을 자동 실행해야 한다면 웹훅의 가치가 커집니다.2
여기서 핵심은 "폴링이 비효율적이냐"보다 "완료 이벤트가 제품 흐름의 일부냐"입니다. 완료 시점에 알림을 보내고, 다음 작업을 이어 붙이고, 감사 로그를 남기고, 사람 검토 단계로 넘겨야 한다면 웹훅은 자연스럽습니다. 그냥 나중에 한 번 결과를 조회하면 되는 시스템이라면, 오히려 큐와 배치 조회가 더 단순할 수 있습니다.
즉, 웹훅은 현대적이라서 쓰는 기능이 아니라, 비동기 완료를 제품 경험으로 끌어올릴 때 쓰는 기능입니다.
Gemini가 앱을 "다시 호출"하기 시작하면 달라지는 것
확인된 사실부터 보자면, Gemini API 웹훅은 Standard Webhooks 규격을 따른다고 밝혔고, webhook-signature, webhook-id, webhook-timestamp 헤더로 서명과 재전송 방어를 지원합니다. 전달 보장은 at-least-once이며, 실패 시 최대 24시간 자동 재시도가 이뤄집니다.1
이건 곧 같은 이벤트가 두 번 이상 올 수 있다는 뜻입니다. 따라서 앱은 "한 번만 오겠지"라는 전제에서 벗어나야 합니다. webhook-id 기준 중복 제거, 이미 처리된 작업의 재실행 방지, 순서가 바뀐 이벤트 처리 같은 기본기가 필요합니다. 웹훅은 폴링 코드를 지워주지만, 그 대신 이벤트 소비자 설계를 요구합니다.
UX도 바뀝니다. 기존에는 사용자가 새로고침하거나 "결과 확인" 버튼을 누르는 흐름이었다면, 이제는 "처리 중 → 완료됨 → 후속 단계 실행"이 자연스러운 비동기 인터페이스가 됩니다. 모델이 더 빨라진 건 아니어도, 사용자는 덜 기다리는 느낌을 받습니다. 완료 즉시 이메일, 푸시, 슬랙 알림, 검토 요청, 다음 에이전트 실행까지 이어붙일 수 있기 때문입니다.
다만 반론도 있습니다. 웹훅이 늘 더 단순한 건 아닙니다. 방화벽, 공개 엔드포인트, 재시도 폭주, 장애 시 관측성 부족까지 감당해야 합니다. 소규모 팀이라면 "몇 분마다 상태 확인"이 오히려 운영상 더 안전할 수 있습니다.
데모가 아니라 운영으로 가려면 필요한 최소 체크리스트
실무에서는 세 가지만 먼저 챙기면 됩니다.
첫째, 서명 검증은 필수입니다. 구글은 프로젝트 단위 글로벌 설정에서는 HMAC, 요청별 동적 라우팅에서는 JWKS 기반 구성을 지원한다고 설명합니다.1 어느 방식을 쓰든 검증 실패 요청은 버려야 합니다.
둘째, 빠르게 200을 반환하고 실제 처리는 비동기로 넘겨야 합니다. 웹훅 수신 엔드포인트에서 무거운 작업을 직접 돌리면 재시도 루프가 생기기 쉽습니다.
셋째, 폴백 폴링을 남겨두는 편이 안전합니다. 웹훅은 전달 보장을 제공하지만, 애플리케이션 쪽 버그나 잘못된 배포까지 해결해주진 않습니다. 장기 실행 작업 상태를 operations.get 같은 방식으로 다시 확인하는 백업 경로가 있으면 복구가 훨씬 쉽습니다.3
추가로 있으면 좋은 것들도 분명합니다. 재생 공격 방지를 위한 타임스탬프 검사, 비밀 키 교체 절차, 전용 엔드포인트 분리, 수신/처리 로그, 데드레터 큐, 로컬 테스트 도구입니다. 이런 항목은 화려하지 않지만, 실제 장애는 대개 여기서 갈립니다.
진짜 이득은 API 호출 절감보다 더 나은 AI 제품 경험이다
이번 변화의 숨은 장점은 비용 절감보다 제품 설계 자유도에 있습니다.
배치 처리 결과가 도착하면 바로 DB를 갱신하고, 사람 승인 대기열로 보내고, 다음 모델 호출을 이어가고, 외부 시스템과 동기화하는 흐름이 쉬워집니다. 이건 특히 에이전트형 제품에 중요합니다. AI가 단발성 응답기가 아니라 여러 단계를 거치는 작업자처럼 동작할수록, "끝났는지 계속 묻는" 구조는 금방 한계에 부딪힙니다.
그래서 이번 웹훅 지원은 작은 기능 추가처럼 보여도, 신호는 분명합니다. AI API가 즉시 응답 중심 도구에서 이벤트 중심 인프라로 조금씩 이동하고 있다는 뜻입니다.
지금 이 변화를 가장 진지하게 봐야 하는 팀은 세 부류입니다. 장시간 생성 작업을 다루는 팀, 배치/에이전트 워크플로를 운영하는 팀, 그리고 완료 시점에 후속 액션이 많은 팀입니다. 반대로 짧은 요청-응답형 앱이라면 서두를 필요는 없습니다. 판단 기준은 간단합니다. "폴링이 귀찮은가"가 아니라, "완료 이벤트가 우리 제품의 핵심 흐름인가"입니다.
참고
1Reduce friction and latency for long-running jobs with Webhooks in Gemini API
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.