客户端的订阅和断开不会到达您的后端，这意味着您的后端无法知道是否有人在监听。Webhooks 弥补了这一缺口：当频道有人加入或清空时、当成员到达或离开时、当缓存频道没有内容可提供时，边缘节点会发送一个签名事件。
app.post("/webhooks/bird", express.raw({ type: "*/*" }), (req, res) => {
const event = bird.webhooks.unwrap(req.body, req.headers);
res.sendStatus(200);
switch (event.type) {
case "realtime.channel_occupied":
startStreaming(event.data.channel);
break;
case "realtime.channel_vacated":
stopStreaming(event.data.channel);
break;
case "realtime.cache_miss":
backfill(event.data.channel);
break;
default:
break;
}
});
别再为无人收听的频道付费。
这是 Bird Realtime 中最经济的优化。channel-occupied 事件是启动高开销任务的信号——行情数据订阅、每秒发布循环；channel-vacated 则是停止的信号。中间订阅者的加入和离开不会触发任何事件，因此这两个事件精确标记了频道生命周期的起止，仅此而已。
五个事件组。按需订阅。
您订阅一个组，该组会推送其中的各个事件类型。一个端点可以同时接收实时事件和平台其他事件，因此 email.bounced 和 realtime.presence 可以到达同一路由，使用相同的签名密钥。
{
"type": "realtime.member_added",
"timestamp": "2026-07-31T09:00:00Z",
"data": {
"channel": "presence-room-1",
"member_id": "u_42"
}
}
realtime.channel_existence频道占用与空出：频道生命周期的两个边界，中间没有多余事件。realtime.presence成员加入与移除。基于身份追踪，同一用户的第二个标签页不会产生额外事件。realtime.connection_count频道当前持有的连接数。需要在应用上启用连接计数。realtime.cache_channels缓存未命中，这是您读取当前状态并发布的信号。realtime.client_events每个客户端事件一次投递，以事件命名：client-typing 会以 realtime.client-typing 的形式到达。
用户用它们构建什么
四种需要服务器了解客户端行为的模式。
- 01
仅在有人观看时运行的任务。
在 channel occupied 时启动上游数据源、轮询器或渲染任务，在 channel vacated 时关闭它们。没有人打开的仪表盘无需保持运行。
- 02
后端的在线名单副本。
member added 和 member removed 让您维护自己的房间成员视图，这正是客服在线指示器或席位计数的本质。它们基于身份追踪，因此一个人关闭三个标签页中的一个不会产生任何事件。
- 03
填充冷缓存。
客户端订阅一个空缓存频道时，会在您的端点上触发未命中事件。读取当前状态并发布，触发未命中的客户端会收到该数据，因为它此时已处于订阅状态。
- 04
监控点对点流量。
客户端事件在客户端之间传输，无需经过您的 API。订阅 client-events 组后，您的服务器会收到副本，包含频道、连接 ID，以及在 presence 频道中的成员 ID。订阅前需要了解：像光标位置这样的高频信号，每个事件都会产生一次投递。
与所有其他 Bird webhook 一样签名。
投递遵循 Standard Webhooks 规范，包含 webhook-id、webhook-timestamp 和 webhook-signature 头，您可通过端点的签名密钥进行验证。SDK 可在一次调用中完成解包和验证。请验证原始请求体而非重新解析的副本，因为重新序列化 JSON 可能改变已签名的字节；同时保留一个默认分支，以防新事件类型导致路由中断。
投递保证，直白说明。
请将这些视为变更通知而非账本。非 2xx 响应会以指数退避方式重试最多五分钟，之后事件将丢失：实时事件不支持重放，也不会出现在端点的投递尝试日志中。投递无序且没有逐事件回执，因此在延迟或丢失后，请通过 channel-state API 读取当前状态，而非尝试重建。在持久化接受事件后立即返回 2xx，后续再处理。
在控制台中配置。
实时订阅在 Webhooks 页面设置：创建或编辑端点，选择一个 Realtime 应用，然后选择事件组。应用创建后不可更改，但事件组可以。这是目前平台 webhook 功能中仅支持控制台操作的部分，包含实时事件类型的公共 API 请求会被拒绝而非静默接受。
在文档中深入了解。
实时 webhooks 列出了所有投递的事件类型及其数据字段。客户端事件 涵盖您自定义命名的事件组，缓存频道 说明了如何处理未命中，webhooks 与事件 是平台级的端点、签名和密钥轮换规范。
付诸实践。
继续查阅此主题的文档、指南和示例。资源为英文。