이벤트 참조
Listings API 웹훅 이벤트 26개 전체를 리소스별로 분류하고, 각 이벤트의 정확한 필드와 예제 페이로드를 제공합니다.
26개의 이벤트를 관련 REST 리소스별로 분류했습니다. 이 페이지의 모든 이벤트는 하나의 웹훅 URL로 전송됩니다. 이벤트별 구독은 없으므로 event에 따라 분기하고 필요하지 않은 이벤트는 무시합니다.
아래에서 별도로 설명하는 listing.submission을 제외한 모든 이벤트는 표준 페이로드를 사용합니다. data 내의 선택적 필드는 비어 있으면 null로 전송되지 않고 생략됩니다.
목차
등록 정보
등록 정보 엔드포인트, 특히 이 이벤트가 알리는 인용 정보별 syncStatus 및 listingUrl를 반환하는 GET /locations/{locationId}/listings/premium와 함께 사용합니다.
listing.submission
발생 조건: 1개 사업장의 인용 정보를 1개 디렉터리 사이트에 제출하는 작업이 최종 상태에 도달합니다.
최상위 수준:
data 내부:
{ "event": "listing.submission", "data": { "business_id": 279381, "v4_business_id": "TG9jYXRpb246Mjc5Mzgx", "location_id": "TG9jYXRpb246Mjc5Mzgx", "site": { "id": 42, "name": "Yelp", "url": "https://www.yelp.com" } }, "status": "success", "live_link": "https://www.yelp.com/biz/acme-dental-downtown"}사업장
사업장 수명 주기 이벤트는 createLocation, updateLocation 및 archiveLocations와 1:1로 대응합니다. 사업장 범위의 이벤트이며, location_id는 항상 숫자 문자열입니다.
profile.created
발생 조건: 새 사업장이 생성됩니다.
{ "event": "profile.created", "timestamp": "2026-08-25T10:04:00Z", "account_id": 11073, "location_id": "901234", "data": { "source": "api" }}profile.updated
발생 조건: 기존 사업장의 세부 정보가 수정됩니다.
사업장별로 60초당 1회만 전송하도록 디바운스 처리되며, 구간 시작 시 전송됩니다. 해당 구간 내의 수정은 지연 전송되지 않고 하나로 통합됩니다. 해당 수정에 대한 이벤트는 전송되지 않습니다. changed_fields는 전체 변경 내역이 아니라 해당 구간을 시작한 수정에 대한 참고 정보로 취급합니다.
이벤트는 구간의 시작 시점에 도착하므로, 수신 즉시 사업장을 다시 조회하면 첫 번째 수정만 확인할 수 있습니다. 이 구간이 끝난 뒤인 최소 60초 후에 두 번째 조회를 수행하도록 예약하고, 이 이벤트는 전송을 1회만 시도하고 재시도하지 않으므로 사업장 데이터도 주기적으로 대조하여 일치시킵니다. 누락된 이벤트 복구를 참조합니다.
{ "event": "profile.updated", "timestamp": "2026-08-25T10:06:12Z", "account_id": 11073, "location_id": "901234", "data": { "source": "user", "changed_fields": ["name", "phone"] }}profile.deleted
발생 조건: 사업장이 보관 처리됩니다. 이는 소프트 삭제입니다. 하드 삭제는 없으며 cancelArchiveLocations로 보관 처리를 취소할 수 있지만, 이 작업은 이벤트를 발생시키지 않습니다.
{ "event": "profile.deleted", "timestamp": "2026-08-25T10:20:44Z", "account_id": 11073, "location_id": "901234", "data": { "source": "user" }}연결된 계정
연결된 계정 엔드포인트와 관련된 Google 및 Facebook 연결의 수명 주기와 상태입니다. 사업장 범위로 적용됩니다. platform은 항상 google 또는 facebook이며, 다른 제공자는 이러한 이벤트를 발생시키지 않습니다.
connected_account_id은 항상 키로 존재하지만, 2개의 Google 인증 이벤트에서는 null입니다.
connection.location_connected
발생 조건: Google 또는 Facebook 등록 정보가 사업장에 연결됩니다.
{ "event": "connection.location_connected", "timestamp": "2026-08-25T14:32:10Z", "account_id": 11073, "location_id": "279381", "data": { "platform": "google", "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc" }}connection.location_disconnected
발생 조건: Google 또는 Facebook 등록 정보와 사업장의 연결이 해제됩니다.
{ "event": "connection.location_disconnected", "timestamp": "2026-08-25T14:35:02Z", "account_id": 11073, "location_id": "279381", "data": { "platform": "google", "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc" }}connection.reauth_required
발생 조건: 연결된 계정의 자격 증명이 무효화되었습니다. 누군가 다시 권한을 부여할 때까지 이 연결에서는 아무것도 동기화되지 않습니다.
{ "event": "connection.reauth_required", "timestamp": "2026-08-25T14:40:18Z", "account_id": 11073, "location_id": "279381", "data": { "platform": "google", "connected_account_id": "ba03bc4b-9f8c-4d3b-8e93-9628034c63cc", "reason": "Google credentials are invalid. Please reconnect." }}connection.listing_inaccessible
발생 조건: 연결된 계정이 더 이상 사업장의 등록 정보에 접근할 수 없습니다. reauth_required과는 다릅니다. 자격 증명은 여전히 유효할 수 있지만, 해당 등록 정보에 대한 접근 권한이 제거된 상태입니다.
{ "event": "connection.listing_inaccessible", "timestamp": "2026-08-25T14:42:55Z", "account_id": 11073, "location_id": "279381", "data": { "platform": "facebook", "connected_account_id": "cf12de77-2211-4a09-b7c1-0a6f3b2e91aa", "reason": "No longer has access to this listing." }}connection.google_verification_verified
발생 조건: 사업장의 Google Business Profile이 인증을 통과합니다.
{ "event": "connection.google_verification_verified", "timestamp": "2026-08-25T14:50:00Z", "account_id": 11073, "location_id": "279381", "data": { "platform": "google", "connected_account_id": null }}connection.google_verification_failed
발생 조건: Google Business Profile 인증이 최종 실패 상태에 도달합니다. 인증을 시작하는 REST 호출은 없으며, 상태 자체는 위에서 설명한 대로 조회할 수 있습니다.
최종 상태에서만 이벤트가 발생합니다. VERIFIED은 _verified 이벤트를 발생시키고, SUSPENDED 또는 DUPLICATE(failure_type rejected)과 ERROR_WHILE_FETCHING(transient)은 이 이벤트를 발생시킵니다. 진행 중 상태(PENDING_VERIFICATION, UNDER_REVIEW, NOT_VERIFIED, NOT_CONNECTED)에서는 이벤트가 전혀 발생하지 않으므로, 이벤트가 없다는 사실만으로는 상태를 판단할 수 없습니다. 인증이 진행 중인 동안 사업장을 조회하여 googleVerificationStatus을 폴링합니다.
{ "event": "connection.google_verification_failed", "timestamp": "2026-08-25T14:52:31Z", "account_id": 11073, "location_id": "279381", "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}리뷰
답글 작성, 답글 수정, 답글 보관을 포함한 리뷰 엔드포인트와 관련된 리뷰 및 답글입니다.
Social 카테고리의 리뷰는 필터링되어 전달되지 않습니다.
interaction.review
발생 조건: 리뷰가 수집되거나 변경됩니다.
{ "event": "interaction.review", "timestamp": "2026-08-25T09:12:44Z", "account_id": 11073, "location_id": "279381", "data": { "interaction": { "id": "6f8a1d20-3e11-4a55-9f7d-2b0c9e5a4471", "type": "Review", "content": "Friendly staff and no waiting.", "rating": 5, "title": null, "author_name": "Dana R.", "author_avatar": "https://lh3.googleusercontent.com/a/example", "date": "2026-08-25T08:58:02Z", "source": "google.com", "permalink": "https://maps.google.com/example-review", "category": "Review", "interaction_status": "unread", "parent_id": null, "interaction_request_id": "3c1e9b74-88a2-4d0e-9c31-77a1f0be5d92" } }}interaction.response
발생 조건: 리뷰에 대한 답글이 게시, 수정 또는 보관됩니다. interaction.review과 구조는 같지만 2가지 차이가 있습니다. type은 Response이고, parent_id은 답글 대상 리뷰를 가리킵니다.
interaction.review에 나열된 나머지 모든 필드도 동일한 의미로 포함됩니다.
{ "event": "interaction.response", "timestamp": "2026-08-25T09:30:07Z", "account_id": 11073, "location_id": "279381", "data": { "interaction": { "id": "b2d7c095-5f43-4e21-8a10-6d9c3f77e208", "type": "Response", "content": "Thanks Dana, see you next time!", "rating": null, "author_name": "Acme Dental Downtown", "date": "2026-08-25T09:29:55Z", "source": "google.com", "permalink": "https://maps.google.com/example-review", "category": "Review", "interaction_status": "responded", "parent_id": "6f8a1d20-3e11-4a55-9f7d-2b0c9e5a4471", "interaction_request_id": "3c1e9b74-88a2-4d0e-9c31-77a1f0be5d92" } }}게시물
게시물 엔드포인트와 관련된 Google Business Profile 로컬 게시물입니다. 사업장 단위이며, location_id은 숫자로 구성된 문자열입니다.
4개의 이벤트는 동일한 data 구조를 사용하며, 선택 필드만 다릅니다. 모든 선택 필드는 값이 비어 있으면 생략됩니다.
local_post.created
발생 조건: 게시물 항목이 생성되고 Google에 제출하기 위한 대기열에 추가됩니다. 아직 공개되지는 않은 상태입니다.
{ "event": "local_post.created", "timestamp": "2026-08-25T11:02:00Z", "account_id": 11073, "location_id": "279381", "data": { "post_id": 88421, "post_item_id": 5512309, "post_type": "STANDARD" }}local_post.published
발생 조건: Google이 게시물을 수락했으며 게시물이 공개되었습니다.
{ "event": "local_post.published", "timestamp": "2026-08-25T11:06:41Z", "account_id": 11073, "location_id": "279381", "data": { "post_id": 88421, "post_item_id": 5512309, "post_type": "STANDARD", "post_external_id": "accounts/123/locations/456/localPosts/789" }}local_post.rejected
발생 조건: Google이 게시물을 거부했거나 제출에 실패했습니다.
{ "event": "local_post.rejected", "timestamp": "2026-08-25T11:07:15Z", "account_id": 11073, "location_id": "279381", "data": { "post_id": 88421, "post_item_id": 5512310, "post_type": "OFFER", "rejection_reason": "Rejected" }}local_post.deleted
발생 조건: 게시물 항목이 삭제됩니다.
{ "event": "local_post.deleted", "timestamp": "2026-08-25T15:40:09Z", "account_id": 11073, "location_id": "279381", "data": { "post_id": 88421, "post_item_id": 5512309, "post_type": "STANDARD", "post_external_id": "accounts/123/locations/456/localPosts/789" }}Social
Social 엔드포인트와 관련된 브랜드 단위의 소셜 게시 및 연결 수명 주기입니다. 이벤트는 게시물 관련 5개와 연결 관련 4개로, 총 9개입니다.
account_id과 timestamp은 평소와 같이 포함됩니다. data 내부의 ID는 REST API에서 사용하는 것과 동일한 일반 UUID이며, 문자열로 전송됩니다.
social_post.created
발생 조건: 소셜 게시물이 생성됩니다. 생성 시에만 발생하며, 기존 게시물을 수정해도 다시 발생하지 않습니다.
{ "event": "social_post.created", "timestamp": "2026-09-28T14:02:11Z", "account_id": 62570, "location_id": null, "data": { "post_id": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345", "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "status": "scheduled", "created_by": 40122, "platform_ids": [1, 2, 4] }}social_post.published
발생 조건: 게시물이 완전히 공개되었습니다. 이 이벤트는 완전히 성공한 경우에만 발생하며, 하나 이상의 채널에서 게시에 성공하고 오류가 발생한 채널이 없어야 합니다. 일부 채널에서만 게시에 성공한 경우에는 이 이벤트가 발생하지 않으며, 대신 social_post.failed이 발생합니다.
{ "event": "social_post.published", "timestamp": "2026-10-02T13:30:07Z", "account_id": 62570, "location_id": null, "data": { "post_id": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345", "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "status": "published", "published_on": "2026-10-02T13:30:04", "items": [ { "platform": "instagram", "social_platform_id": 2, "connected_account_id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7", "published_url": "https://www.instagram.com/p/CxYz1234abc/", "vendor_post_id": "18029384756012345", "status": "success" } ] }}social_post.failed
발생 조건: 게시에 실패했습니다. 이는 콘텐츠 검토에 따른 거부와 구분되는 전송 실패입니다. 마지막 재시도 시점에 발생하므로, 게시물에 남은 시도 횟수가 있으면 발생하지 않습니다.
items에는 오류가 발생한 채널만 포함되므로, 2개 플랫폼에서 게시에 성공하고 3번째 플랫폼에서 실패한 게시물은 이 이벤트에 항목 1개로 전달됩니다.
{ "event": "social_post.failed", "timestamp": "2026-10-02T13:34:55Z", "account_id": 62570, "location_id": null, "data": { "post_id": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345", "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "status": "failed", "items": [ { "platform": "linkedin", "social_platform_id": 4, "status": "error", "reason": "Authorization expired", "vendor_error": "The access token is no longer valid." } ] }}social_post.rejected
발생 조건: 승인 워크플로에서 게시물이 거부되었습니다. 전송 실패가 아닌 콘텐츠 검토에 따른 거부이며, 게시물은 플랫폼에 전달되지 않았습니다.
{ "event": "social_post.rejected", "timestamp": "2026-09-29T09:11:03Z", "account_id": 62570, "location_id": null, "data": { "post_id": "e08b2d97-6f14-4c22-b7a5-9d3e1f6c4a70", "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "status": "rejected", "rejection_reason": "Please use the updated product name." }}social_post.deleted
발생 조건: POST /social/posts/cancel 또는 예약된 보관 처리 작업을 통해 게시물이 보관되었습니다. 실제로 상태가 전환될 때만 발생하므로, 이미 보관된 게시물을 다시 보관해도 이벤트는 발생하지 않습니다.
{ "event": "social_post.deleted", "timestamp": "2026-09-30T16:20:41Z", "account_id": 62570, "location_id": null, "data": { "post_id": "e08b2d97-6f14-4c22-b7a5-9d3e1f6c4a70", "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "status": "archived", "archived_at": "2026-09-30T16:20:39" }}social_connection.connected
발생 조건: 최초 연결 또는 보관되었던 채널의 재연결로 브랜드 채널이 활성화되었습니다. is_reconnect으로 두 경우를 구분합니다.
{ "event": "social_connection.connected", "timestamp": "2026-09-27T11:05:22Z", "account_id": 62570, "location_id": null, "data": { "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "connected_account_id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7", "platform": "instagram", "display_name": "Jenny Home", "is_reconnect": false }}social_connection.disconnected
발생 조건: disconnect 호출로 채널이 의도적으로 제거되었습니다. 채널이 실제로 보관된 경우에만 발생하므로, 연결 해제에 실패해도 잘못된 이벤트가 발생하지 않습니다.
{ "event": "social_connection.disconnected", "timestamp": "2026-10-04T08:47:10Z", "account_id": 62570, "location_id": null, "data": { "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "connected_account_id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7", "platform": "instagram", "display_name": "Jenny Home" }}social_connection.archived
발생 조건: 플랫폼이 토큰을 무효화했거나 상태 대조 작업에서 채널에 더 이상 접근할 수 없음을 확인하여 채널 연결이 의도치 않게 끊어졌습니다. 아무도 연결 해제를 요청하지 않았다는 점에서 disconnected과 구분됩니다.
{ "event": "social_connection.archived", "timestamp": "2026-10-06T02:15:33Z", "account_id": 62570, "location_id": null, "data": { "social_profile_id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902", "connected_account_id": "2d4e6f80-1c33-4b7a-8e05-9a1b2c3d4e5f", "platform": "facebook", "display_name": "Jenny Home & Co.", "reason": "Access token has been invalidated by the platform." }}리뷰 분석
예약된 리뷰 집계로, 사업장별로 기간마다 이벤트 1개가 발생합니다.
두 이벤트는 동일한 data 구조를 사용합니다.
해당 기간에 활동이 없는 사업장은 아무 이벤트도 내보내지 않지만, 스냅샷이 전달되지 않은 사업장에서도 아무 이벤트도 수신되지 않습니다. 스냅샷이 없다는 사실만으로는 원인을 알 수 없으며, 이 이벤트 유형에서는 문제가 없는 경우일 가능성이 가장 낮습니다. 가능한 원인은 활동 없음, 전송 실패 또는 시간 초과(전송은 1번 시도하며 재시도하지 않습니다), 계정에 웹훅 사용 권한이 없거나 URL이 설정되지 않았거나 계정이 미인증 또는 차단 상태여서 전송이 차단된 경우, 또는 여기서 가장 가능성이 높은 원인으로 분당 한도로 인해 한꺼번에 몰린 요청 중 일부가 rate_limited로 처리되어 누락된 경우입니다.
스냅샷이 없다는 이유만으로 절대 0을 기록하지 않습니다. 같은 기간의 GET /locations/{locationId}/review-analytics-overview 결과와 대조하고, 해당 조회도 실패하면 그 기간을 0이 아닌 사용 불가로 보고합니다.
review_analytics.daily_snapshot
트리거: 일별 집계 작업이며, 사업장별로 하루에 1번 실행됩니다.
{ "event": "review_analytics.daily_snapshot", "timestamp": "2026-08-25T02:00:00Z", "account_id": 11073, "location_id": "279381", "data": { "period": "2026-08-24", "granularity": "daily", "total_reviews": 1240, "new_reviews_in_period": 3, "average_rating": 4.6667, "previous_average_rating": 5.0 }}review_analytics.weekly_snapshot
트리거: 주별 집계 작업이며, 사업장별로 주 1번 실행됩니다. period는 집계 대상 주의 첫날입니다.
{ "event": "review_analytics.weekly_snapshot", "timestamp": "2026-08-24T02:00:00Z", "account_id": 11073, "location_id": "279381", "data": { "period": "2026-08-17", "granularity": "weekly", "total_reviews": 1237, "new_reviews_in_period": 18, "average_rating": 4.6123, "previous_average_rating": 4.5901 }}수신할 수 있지만 구현의 기반으로 삼아서는 안 되는 이벤트
플랫폼은 리뷰 캠페인, 순위, 소셜 게시물 홍보, 소셜 광고 계정 상태 변경, AI 게시물 아이디어, Google Business Profile 소유권과 같은 다른 이벤트 유형도 내보냅니다. 이러한 유형에는 Listings API에서 공개한 REST 엔드포인트가 없고, 이 문서에서 다루지 않으며, 구조에 대한 호환성도 보장하지 않습니다. URL은 1개이고 이벤트별 구독은 없으므로, 핸들러는 인식하지 못하는 event를 무시하고 이 경우에도 200를 반환해야 합니다.