Webhooks 概述
了解 Listings API 如何将账户事件推送到您的服务器、支持哪些事件，以及每次投递必须通过的 5 项检查。
通过轮询 API 来检测变更成本较高，而且总会有些延迟。Webhook 则采用相反的方式：当您的账户中发生事件（收到评价、地点被编辑、Google Business 帖子上线）时，Listings API 会在几秒内向您控制的 URL 发送带有 JSON 正文的 HTTP POST 请求。
每个账户只有 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 个条件。任何一个条件不满足，都会停止投递，不再检查后续条件。
套餐与限额
所有套餐均包含 webhook 使用权限：Launch、Growth 和 Enterprise。试用使用您选择的套餐，因此试用账户从第 1 天起就可以使用 webhook，并受该套餐的限额约束。此权限与您的套餐关联，因此会在套餐变更处理过程中授予或移除，而非立即生效：请以您的下一次套餐变更或注册同步完成时为生效时间，而不是点击升级的那一刻。控制台的 Webhooks 页面会显示您当前的使用权限和限额。
投递量还受每分钟和每天的限额约束，两项限额均由您的套餐决定。
Webhook 限额与您套餐的 API 请求限额相同：我们向您发送事件的配额，等于您向我们发送请求的配额。
只有在您套餐的限额同步到投递流程后，限额才开始对您的账户生效。在此之前，没有可供检查的限额，因此不会计量，也不会丢弃事件。所以，新账户可能会先经历一段不计量的投递期，之后才受到套餐限额约束。不要因为没有出现 rate_limited 就认定您未超出限额。
计量规则如下：
- 两个独立的固定窗口：一个按分钟计量，一个按天计量。Webhook 没有按小时计量的窗口。（请求速率限制器是另一套系统，使用不同的窗口；两者不共享配额。）
- 窗口按自然时间边界对齐，而非滑动窗口：分钟计数器在每分钟开始时重置，每日计数器在 UTC 每天开始时重置。
- 超出限额时，事件会被丢弃。不会排队、延迟或重试：整个出站投递流程中都没有重试队列，也没有可接收
429返回值的调用方。此次尝试会以投递状态rate_limited记录，因此事件丢失可查，不会悄无记录。 - 限流器故障时会放行。如果限流器本身无法返回判断结果，仍会投递事件，不会丢弃。您不会因为计量器故障而丢失事件。
事件产生端唯一内置的数量控制是对 profile.updated 进行防抖：每个地点每 60 秒最多投递 1 次，在窗口开始时触发。对同一地点的快速连续编辑会合并为一个事件，而您收到的 changed_fields 仅描述开启该窗口的那次编辑。其他事件均不进行防抖。
由于投递在窗口开始时触发，您会在 60 秒窗口的开始时收到事件：如果收到事件后立即回读，只能看到第一次编辑。请在窗口关闭后，也就是事件发生至少 60 秒后，安排第二次回读，并定时核对地点数据，因为事件本身只尝试投递 1 次，不会重试。请参阅遗漏事件后的恢复处理。
配置
- 部署 HTTPS 端点。该端点必须可通过公网解析，具有有效证书，接受
POST，并在不到 5 秒内返回2xx。私有地址和内部地址（环回地址、RFC-1918 地址、链路本地地址、云元数据 IP 地址）均不被接受。 - 在控制台的 Webhooks 页面上保存您的 webhooks URL。每个账户使用 1 个 URL，接收所有事件。
- 生成签名密钥并将其存储在您的服务器上。密钥仅显示 1 次。从此刻起，投递将附带签名，并且必须完成验证。
- 验证端点。平台会发送带签名的质询；您的端点需返回 nonce 的十六进制 HMAC。验证成功后，端点状态将变为已验证，并开始投递。有关确切的交互规范和可运行的代码，请参阅签名与验证。
- 处理事件。验证签名，将有效负载加入队列，然后返回
200。实际业务处理应在请求处理流程之外执行。有关超时时间、仅尝试 1 次的策略，以及重复投递和顺序方面的行为，请参阅投递行为。