웹훅 개요
Listings API가 계정 이벤트를 서버로 전송하는 방식, 지원하는 이벤트 종류, 모든 전송이 통과해야 하는 5가지 조건을 설명합니다.
변경 사항을 확인하기 위해 API를 폴링하면 비용이 많이 들고 항상 약간의 지연이 발생합니다. 웹훅은 이 방식을 반대로 바꿉니다. 계정에서 어떤 일이 발생하면(리뷰가 도착하거나, 사업장이 수정되거나, Google Business 게시물이 게시되면), Listings API가 몇 초 이내에 JSON 본문을 포함한 HTTP POST 요청을 직접 관리하는 URL로 보냅니다.
계정당 웹훅 URL은 1개이며 이벤트별 구독은 없습니다. 계정에서 웹훅이 활성화되어 있고 엔드포인트가 검증되었다면, 이 페이지에 나열된 모든 이벤트가 해당 URL 1개로 전달됩니다. event 필드를 기준으로 분기하고 필요하지 않은 이벤트는 무시합니다.
전달 파이프라인
수신할 수 있는 이벤트
6개 그룹에 총 18개의 이벤트가 있습니다. 각 이벤트는 REST API로 이미 관리하고 있는 리소스에 대응하므로, 웹훅은 언제 변경되었는지 알려주고 엔드포인트는 무엇이 변경되었는지 알려줍니다.
전체 필드 표와 페이로드 예시는 이벤트 참조에 있습니다.
지원 범위에 포함되지 않는 이벤트
플랫폼은 Listings API에서 문서화하거나 지원하지 않는 다른 이벤트 그룹도 내보냅니다. 여기에는 해당 그룹에 대해 공개된 REST 엔드포인트가 없기 때문입니다. 실수로 누락된 것으로 보이지 않도록 아래에 나열합니다:
- 리뷰 캠페인:
campaign.* - 순위:
rankings.* - Social 게시물 및 홍보:
social_post.* - Social 연결:
social_connection.* - AI 게시물 아이디어:
idea.*,idea_series.*,idea_pipeline.*,idea_image.* - Google Business Profile 소유권:
gbp_ownership.*
구현 전에 확인해야 할 2가지 주의 사항
전달 조건
전달 여부는 5가지 조건에 따라 결정되며, 아래 순서대로 확인합니다. 조건 중 하나라도 충족하지 못하면 해당 단계에서 전달을 중단하며, 이후 조건은 확인하지 않습니다.
요금제 및 한도
웹훅 사용 권한은 Launch, Growth, Enterprise의 모든 요금제에 포함됩니다. 체험 기간에도 선택한 요금제가 적용되므로, 체험 계정은 첫날부터 해당 요금제의 한도 내에서 웹훅을 사용할 수 있습니다. 사용 권한은 요금제에 연결되어 있으므로 즉시 부여되거나 제거되는 것이 아니라 요금제 변경 과정에서 부여되거나 제거됩니다. 따라서 업그레이드를 클릭한 순간이 아니라 다음 요금제 변경 또는 가입 동기화 시점에 적용됩니다. 대시보드의 Webhooks 페이지에서 현재 적용 중인 사용 권한과 한도를 확인할 수 있습니다.
전달 횟수는 분당 한도와 일일 한도를 기준으로도 집계하며, 두 한도 모두 요금제에 따라 정해집니다.
웹훅 한도는 요금제의 API 요청 빈도 제한과 같습니다. 즉, 서비스에서 계정으로 보내는 이벤트의 허용량은 계정에서 서비스로 보내는 요청의 허용량과 같습니다.
요금제 한도가 전달 경로에 동기화된 후에만 계정에 한도가 적용되기 시작합니다. 그전에는 확인할 한도가 없으므로 전달 횟수를 집계하지 않으며 이벤트를 삭제하지도 않습니다. 따라서 새로 생성한 계정에서는 요금제 한도가 적용되기 전에 집계 없이 이벤트가 전달될 수 있습니다. rate_limited이 없다는 사실을 한도 이내라는 증거로 해석해서는 안 됩니다.
집계 방식은 다음과 같습니다.
- 서로 독립적인 고정 집계 구간 2개를 사용하며, 하나는 1분 단위이고 다른 하나는 1일 단위입니다. 웹훅에는 시간당 집계 구간이 없습니다. (요청 속도 제한기는 다른 집계 구간을 사용하는 별도 시스템이며, 두 시스템은 허용량을 공유하지 않습니다.)
- 집계 구간은 달력과 시각의 경계에 맞춰 고정되며, 이동하지 않습니다. 분당 카운터는 매분 시작 시점에, 일일 카운터는 UTC 기준으로 날짜가 바뀌는 시점에 초기화됩니다.
- 한도를 초과하면 이벤트를 삭제합니다. 대기열에 넣거나 지연하거나 재시도하지 않습니다. 발신 경로 어디에도 재시도 대기열이 없으며,
429을 반환할 호출자도 없습니다. 누락 사실을 확인할 수 있도록 해당 시도의 전달 상태를rate_limited으로 기록합니다. - 제한기가 실패하면 전달을 허용합니다. 제한기 자체가 응답하지 못하면 이벤트를 삭제하지 않고 전달합니다. 집계 기능의 장애로 이벤트가 누락되는 일은 없습니다.
이벤트 생성 측에 내장된 유일한 전송량 제어 기능은 profile.updated에 적용되는 디바운스입니다. 사업장별로 60초당 최대 1회 전달하며, 구간 시작 시점에 전달합니다. 같은 사업장을 짧은 시간에 여러 번 수정하면 하나의 이벤트로 합쳐지며, 수신하는 changed_fields에는 해당 구간을 시작한 수정 사항만 포함됩니다. 그 외에는 디바운스를 적용하지 않습니다.
전달이 구간 시작 시점에 이루어지므로 이벤트는 60초 구간의 시작에 도착하며, 이벤트 수신을 계기로 데이터를 다시 조회하면 첫 번째 수정 사항만 확인할 수 있습니다. 이벤트 발생 후 최소 60초가 지나 구간이 종료된 뒤 두 번째 조회가 실행되도록 예약하고, 이벤트 자체는 전달을 1회만 시도하고 재시도하지 않으므로 사업장 데이터도 주기적으로 대조하여 동기화합니다. 누락된 이벤트 복구를 참고합니다.
설정하기
- HTTPS 엔드포인트를 구성합니다. 공개적으로 주소를 확인할 수 있고 유효한 인증서가 있어야 하며,
POST를 수신하고 5초 미만에2xx로 응답해야 합니다. 사설 및 내부 주소(loopback, RFC-1918, link-local, 클라우드 메타데이터 IP)는 허용되지 않습니다. - 대시보드의 Webhooks 페이지에서 웹훅 URL을 저장합니다. 계정당 URL 1개를 모든 이벤트에 사용합니다.
- 서명 비밀 키를 생성하고 서버에 저장합니다. 비밀 키는 1번만 표시됩니다. 이 시점부터 전송에 서명이 적용되며 검증이 필수입니다.
- 엔드포인트를 검증합니다. 플랫폼이 서명된 검증 요청을 보내면 엔드포인트는 nonce의 HMAC을 16진수로 반환합니다. 성공하면 엔드포인트가 검증 완료 상태로 전환되고 전송이 시작됩니다. 정확한 규약과 작동하는 코드는 서명 및 검증을 참조합니다.
- 이벤트를 처리합니다. 서명을 검증하고, 페이로드를 큐에 넣고,
200를 반환합니다. 실제 작업은 요청 처리 과정과 분리하여 수행합니다. 시간 제한, 단일 시도 정책, 중복 및 순서에 관한 동작은 전송 동작을 참조합니다.