Webhooks 概覽
Listings API 如何將帳戶事件推送至您的伺服器、有哪些事件，以及每次傳送必須通過的 5 項檢查。
透過輪詢 API 得知變更的成本很高，而且總會有些延遲。Webhook 採用相反的方式：當您的帳戶發生事件（收到評論、地點遭到編輯、Google 商家貼文上線）時，Listings API 會在幾秒內，將含有 JSON 主體的 HTTP POST 請求傳送至您控制的 URL。
每個帳戶只有 1 個 webhook URL，而且無法個別訂閱事件。如果您的帳戶已啟用 webhook，且您的端點已通過驗證，本頁列出的所有事件都會傳送至該 URL。請根據 event 欄位分別處理，並忽略您不需要的事件。
傳送流程
您可以接收的事件
共 6 個類別、18 種事件。每種事件都對應到您已透過 REST API 管理的資源，因此 webhook 告訴您何時發生變更，端點則告訴您變更的內容。
完整的欄位表格與酬載範例請見事件參考文件。
不在支援範圍內
平台也會發出其他類別的事件，但 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 個條件。第一個未通過的條件就會停止傳送，後續條件不會再檢查。
方案與限制
所有方案都包含 webhooks 使用權限：Launch、Growth 和 Enterprise。試用期間會使用您選擇的方案，因此試用帳號從第一天起就能使用 webhooks，並受該方案的上限限制。這項使用權限附屬於您的方案，因此會隨方案變更而授予或移除，不會立即生效：預期會在下一次方案變更或註冊同步時生效，而非在您按下升級時立即生效。儀表板的 Webhooks 頁面會顯示您目前的使用權限與上限。
傳送量也會依照您方案的每分鐘與每日上限計量。
Webhook 上限與您方案的 API 請求限制相同：我們傳送給您的事件配額，等於您傳送給我們的請求配額。
只有在您方案的限制同步至傳送流程後，上限才會開始套用至您的帳號。在此之前，沒有可供檢查的上限，因此不會計量，也不會捨棄任何事件。所以，全新帳號在套用方案上限之前，可能會先收到未經計量的傳送事件。請勿將未出現 rate_limited 視為您尚未超過限制的證據。
計量機制的運作方式：
- 2 個獨立的固定時間區間：一個以分鐘為單位，另一個以日為單位。Webhook 沒有每小時的時間區間。（請求速率限制器 是另一套系統，使用不同的時間區間；兩者不共用配額。）
- 時間區間依時鐘與日期對齊，不採滑動計算：每分鐘計數器會在每分鐘開始時重設，每日計數器則在 UTC 每日開始時重設。
- 超過上限時，事件會遭捨棄。 不會加入佇列、不會延遲傳送，也不會重試：整個對外傳送流程中都沒有重試佇列，也沒有可接收
429回傳值的呼叫端。這次嘗試會以傳送狀態rate_limited記錄，讓您能看出事件遺失，而非毫無記錄。 - 限制器故障時會允許傳送。 如果限制器本身無法回應，事件仍會傳送，不會遭到捨棄。您不會因為計量機制故障而遺失事件。
事件產生端唯一內建的流量控制，是對 profile.updated 採用防彈跳機制：每個地點每 60 秒最多傳送 1 次，並在時間區間開始時立即傳送。短時間內對同一地點進行的多次編輯會合併為單一事件，而您收到的 changed_fields 只會描述觸發該時間區間的那次編輯。其他事件都不採用防彈跳機制。
由於事件會在時間區間開始時立即傳送，因此您會在 60 秒區間的起點收到事件：收到事件後觸發的回讀只會取得第一次編輯的結果。請安排在時間區間結束後，也就是事件發生至少 60 秒後，進行第二次回讀，並定時核對地點資料，因為事件本身只會嘗試傳送 1 次，不會重試。請參閱遺漏事件後的復原方式。
設定
- 架設 HTTPS 端點。此端點必須可透過公用網路解析、具備有效憑證、接受
POST，並在不到 5 秒內回傳2xx。私人與內部位址（loopback、RFC-1918、link-local、雲端中繼資料 IP 位址）均不接受。 - 在儀表板的 Webhooks 頁面上儲存您的 Webhooks URL。每個帳戶使用 1 個 URL，接收所有事件。
- 產生簽章密鑰並儲存在您的伺服器上。密鑰只會顯示 1 次。從此刻起，傳送的內容都會附上簽章，且必須完成驗證。
- 驗證端點。平台會傳送已簽署的挑戰；您的端點須以 nonce 的十六進位 HMAC 回應。驗證成功後，端點會變更為已驗證狀態，並開始傳送事件。如需確切的介面規範與可執行的程式碼，請參閱簽章與驗證。
- 處理事件。驗證簽章、將酬載加入佇列，然後回傳
200。請在請求處理流程之外執行實際工作。如需瞭解逾時限制、僅嘗試傳送 1 次的原則，以及重複事件與事件順序的預期行為，請參閱傳送行為。