Google AI Blog • 26일 전

제미나이 API 웹훅으로 긴 작업 대기시간 단축

IMP

7/10

핵심 요약

구글은 제미나이(Gemini) API에 이벤트 기반 웹훅(Webhook) 기능을 도입하여, 긴 시간이 소요되는 AI 작업 완료를 실시간으로 알려주는 푸시 알림 시스템을 구축했습니다. 이에 따라 개발자들은 더 이상 비효율적인 폴링(Polling) 방식을 사용할 필요 없이 즉각적인 HTTP POST 페이로드를 수신할 수 있게 되었습니다. 이 기능은 표준 웹훅 스펙을 준수하여 높은 보안성과 신뢰성을 보장하며, 현재 모든 제미나이 API 사용자에게 제공됩니다.

번역된 본문

제미나이 API 웹훅으로 긴 작업의 마찰과 지연 시간 줄이기

게시일: 2026년 5월 4일 작성자: Lucia Loher (제미나이 API 프로덕트 매니저), Hussein Hassan Harrirou (제미나이 API 엔지니어링)

오늘 우리는 제미나이 API를 통해 복잡하고 오래 실행되는 에이전트(Agentic) 애플리케이션을 더 쉽고 효율적으로 구축할 수 있게 되었음을 발표합니다. 비효율적인 폴링(Polling)의 필요성을 없애는 푸시 기반 알림 시스템인 이벤트 기반 웹훅(Webhooks)을 도입합니다.

제미나이가 심층 연구(Deep Research), 긴 비디오 생성, 배치(Batch) API를 통한 수천 개의 프롬프트 처리와 같은 에이전트 워크플로 및 대용량 처리로 전환함에 따라, 단일 작업이 완료되는 데 몇 분에서 몇 시간이 걸릴 수 있습니다. 지금까지 개발자들은 작업이 완료되었는지 확인하기 위해 지속적인 폴링(예: GET 작업 반복 호출)에 의존해야 했습니다. 이제 제미나이 API는 작업이 완료되는 즉시 실시간 HTTP POST 페이로드를 개발자의 서버로 푸시할 수 있습니다.

우리는 이 기능을 신뢰성과 보안을 염두에 두고 구축했습니다. 이번 구현은 표준 웹훅(Standard Webhooks) 사양을 엄격하게 준수합니다. 모든 요청은 webhook-signature, webhook-id 및 webhook-timestamp 헤더를 사용하여 서명되며, 이를 통해 멱등성(Idempotency)을 보장하고 재생 공격(Replay attacks)을 방지합니다. 또한 최대 24시간 동안 자동 재시도를 통해 "최소 한 번 이상(At-least-once)"의 전송을 보장합니다.

작동 방식

웹훅은 프로젝트 수준에서 전역적으로(HMAC을 통해 보안 유지) 구성하거나, 특정 작업을 라우팅하기 위해 요청별로 동적으로(JWKS를 통해 보안 유지) 재정의할 수 있습니다. 다음은 Python SDK를 사용하여 배치 작업에 대해 웹훅을 동적으로 구성하는 방법의 간단한 예시입니다:

지금 바로 시작하세요

이 기능은 제미나이 API를 사용하는 모든 개발자에게 현재 제공됩니다:

가이드 읽기: 웹훅 문서를 확인하여 전체 이벤트 카탈로그를 살펴보고 엔드포인트를 보호하는 방법을 알아보세요.
실습: 웹훅과의 엔드투엔드(End-to-End) 통합을 구축하는 데 도움이 되는 종합적인 쿡북(Cookbook)을 준비했습니다.

원문 보기

원문 보기 (영어)

Reduce friction and latency for long-running jobs with Webhooks in Gemini API May 04, 2026 · Share x.com Facebook LinkedIn Mail Copy link We're making it easier and more efficient to build complex, long-running agentic applications with the Gemini API Webhooks. Lucia Loher Product Manager, Gemini API Hussein Hassan Harrirou Engineering, Gemini API Share x.com Facebook LinkedIn Mail Copy link Your browser does not support the audio element. Listen to article This content is generated by Google AI. Generative AI is experimental [[duration]] minutes Voice Speed Voice Speed 0.75X 1X 1.5X 2X Today, we're making it easier and more efficient to build complex, long-running agentic applications with the Gemini API. We are introducing event-driven Webhooks, a push-based notification system that eliminates the need for inefficient polling. As Gemini shifts toward agentic workflows and high-volume processing — like Deep Research, long video generation, or processing thousands of prompts via the Batch API — operations can take minutes or even hours. Until now, developers had to rely on continuous polling (e.g., repeatedly calling GET operations) to check if a job was completed. Now, the Gemini API can simply push a real-time HTTP POST payload to your server the instant a task finishes. We’ve built this with reliability and security in mind. Our implementation strictly adheres to the Standard Webhooks specification. Every request is signed using webhook-signature , webhook-id , and webhook-timestamp headers, ensuring idempotency and preventing replay attacks. We also guarantee "at-least-once" delivery with automatic retries for up to 24 hours. How it works You can configure webhooks globally at the project level (secured via HMAC), or override them dynamically on a per-request basis to route specific jobs (secured via JWKS). Here's a quick example of how you can dynamically configure a webhook for a batch task using the Python SDK: Get started today This feature is available now for all developers using the Gemini API: Read the guide: Check out the Webhooks documentation to explore the full event catalog and learn how to secure your endpoints. Hands-on practice: We've prepared a comprehensive Cookbook to help you build an end-to-end integration with webhooks. POSTED IN:

제미나이 API 웹훅 개발자 도구 API 업데이트 에이전트 AI