Google Calendar API Webhook配置方案与配额限制咨询

方案一：为单个事件配置Webhook（每人300个，共50用户） #

合理性分析 #

这个方案完全不合理。50个用户×300个事件=15000个独立的Webhook订阅，会带来极大的维护负担：

• 单个事件的订阅仅绑定特定事件，一旦事件被删除或更新，订阅直接失效，需要重新创建；
• 每个订阅有7天有效期，每周要批量刷新15000个订阅，操作复杂度极高；
• 推送通知的管理成本陡增，要区分15000个不同订阅的通知来源。

需注意的配额限制 #

• 订阅数量上限：Google对每个用户、每个项目的推送订阅数都有明确限制，15000个订阅很容易触发用户级或项目级的订阅配额上限，导致部分订阅创建失败；
• API请求配额：每次创建/刷新订阅都要调用watch接口，每周15000次刷新请求会大量消耗项目的Calendar API每日请求配额（通常项目级每日配额为10万次左右），挤占其他业务的API调用空间；
• 推送限流：大量订阅会导致Google推送服务器的负载过高，可能触发推送限流，部分通知无法正常送达。

方案二：单个Webhook（日历级）监听所有用户的日历修改 #

核心优势与解决思路 #

这里的“单个Webhook”指为每个用户的整个日历创建一个watch订阅，而非单个事件，50个用户仅需50个订阅，是更优的选择：

• 无需为每个事件单独配置，维护成本极低，订阅刷新仅需每周50次请求；
• 收到推送通知后，可通过通知中的resourceUri定位到对应日历，再调用Events.list接口，配合updatedMin参数（传入上次同步的时间戳），仅拉取变更后的事件，无需全量查询；
• 若仅关心事件插入，可在拉取的事件列表中过滤出created时间晚于上次同步时间的条目即可。

配额影响分析 #

• 订阅配额：50个订阅远低于Google的用户级/项目级订阅上限，几乎不会触发配额问题；
• API请求配额：仅在收到推送通知时才调用Events.list，请求量完全取决于实际的日历变更频率，相比方案一的批量刷新，配额消耗可降低90%以上；
• 推送配额：日历级订阅的推送通知会合并短时间内的多次变更，避免过多通知请求，同时Google对推送通知的频率限制宽松，不会轻易触发限流。

优化建议 #

1. 为每个用户的主日历（或目标日历）创建一个日历级watch订阅，记录每个订阅的channelId和日历ID的对应关系；
2. 本地维护每个日历的最后同步时间戳，每次收到推送后，用该时间戳作为updatedMin参数查询变更事件；
3. 提前1天自动刷新即将过期的订阅（订阅有效期7天），避免订阅失效；
4. 对推送通知做幂等处理，防止重复处理同一变更。

内容的提问来源于stack exchange，提问作者Camille