应该使用 webhooks、轮询还是流式传输？

一个订单更新可能有两个消费者：你的数据库和正在查看订单页面的客户。连接断开时，它们需要不同的恢复行为。

你的数据库需要一条可恢复的事件记录。客户的页面在重新连接后可能只需要最新的订单状态。

有哪四种方式？

Bird 提供 webhooks、Realtime、仪表盘事件流以及可轮询的 API 读取。

使用 webhooks 在服务器上接收事件。使用 Realtime 更新已连接的客户端。SSE 流将资源变更发送到仪表盘会话。轮询让你的应用按计划读取资源状态。

什么时候应该使用 webhooks？

当服务器需要处理事件并恢复未送达的投递时，使用 webhooks。

注册一个可公开访问的 HTTPS 端点，订阅你需要的事件类型。接收端先验证签名，然后存储事件，在开始耗时处理之前确认投递。

Bird 在时间调整前最多进行八次尝试，跨度约 27.5 小时。这个窗口给接收端留出了从故障中恢复的时间。未送达事件重放提供了另一条恢复路径。

基于 webhook-id 去重，因为同一事件可能重复到达。覆盖状态前先比较事件发生时间，因为事件可能乱序到达。

失败的 webhook 重试介绍了恢复限制。重复处理介绍了如何在返回成功前安全存储事件。

什么时候应该使用 Realtime？

当已连接的浏览器或应用需要在服务器发布时实时收到更新，使用 Realtime。

频道是客户端订阅的命名目标。服务器向该名称发布事件，已订阅的客户端通过连接接收事件。这可以在无需刷新的情况下更新订单页面、聊天对话或进度展示。

Realtime 不会重放已断开客户端错过的所有事件。在数据库中保持持久化状态，重新连接后恢复视图。

缓存频道为新订阅者保留最新事件，前提是该缓存值仍然可用。它不保留事件历史。如果客户端离线期间发生了两次更新，缓存的最新值无法恢复中间的更新。

app key 出现在客户端代码中，因此持有该密钥的访客可以读取公开频道。以 private- 开头的频道需要后端授权订阅。presence- 频道还会共享已订阅成员的身份信息。

频道名称接受 1 到 164 个字符，可使用字母、数字和 _ - = @ , . ;。前缀计入该限制，因此在验证生成的名称时需包含前缀。

Realtime 还会在频道获得第一个订阅者或失去最后一个订阅者时发送 webhooks。成员 webhooks 报告哪些成员加入或离开。通过仪表盘配置这些 webhooks。发布/订阅与 webhooks 的关系解释了这两种机制如何配合使用。

Bird 有 SSE 端点吗？

Bird 有一个 SSE 端点 getEventsStream，用于已认证的仪表盘会话。

GET /v1/events/stream 报告 API 资源的变更。通知中包含资源类型、标识符和发生时间，以便仪表盘获取资源数据。

该端点接受仪表盘会话 cookie，不接受 API 密钥，因此基于 API 密钥的集成请使用 webhooks 或轮询。

什么时候应该使用轮询？

当你需要资源状态、无法接收传入请求或没有对应变更的公开事件时，使用轮询。

轮询可用于检查运营商是否批准了你的免费电话号码用于发送短信。Bird 没有针对该验证决定的公开 webhook 事件。通过 bird sms tfn verifications get 或对应的代理工具按计划读取验证状态。该命令操作不在公开的 API bundle 中。

轮询也适用于允许出站请求但无法暴露接收端的网络。如果你只需要当前状态，直接读取资源即可，无需从历史事件重建。

读取和列表操作会消耗组织内每个操作凭证的请求速率限制配额。收到 HTTP 429 响应后，等待一段时间再重新请求。根据应用发现变更的速度需求调整轮询间隔。

Webhooks、Realtime 和请求速率限制介绍了这些方式的配置。

应该选择哪种方式？

根据谁消费更新以及断开连接后需要保留什么来选择。

1. Webhooks：服务器必须处理事件，需要重试和未送达事件恢复时选择。
2. Realtime：已连接的界面需要更新，并能在重新连接后从持久化状态恢复时选择。
3. 轮询：需要资源状态、无法暴露接收端或没有公开事件时选择。
4. SSE 流：用于已认证的 Bird 仪表盘会话。