Los clientes se suscriben y desconectan sin llegar nunca a tu backend, lo que significa que tu backend no sabe si alguien está escuchando. Los webhooks cierran ese ciclo: el edge publica un evento firmado cuando un canal se llena o se vacía, cuando un miembro llega o se va, y cuando un canal de caché no tiene nada que servir.
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;
}
});
Deja de pagar por una audiencia de nadie.
Esta es la optimización más barata en Bird Realtime. Un evento channel-occupied es la señal para iniciar el trabajo costoso, la suscripción a datos de mercado, el bucle de publicación por segundo; channel-vacated es la señal para detenerlo. Nada se dispara para los suscriptores que llegan y se van en el intermedio, así que los dos eventos marcan exactamente los bordes de la vida de un canal y nada más.
Cinco grupos. Suscríbete a lo que necesites.
Te suscribes a un grupo; el grupo entrega los tipos de evento individuales. Un endpoint puede transportar eventos de Realtime junto con el resto de la plataforma, así que email.bounced y realtime.presence pueden llegar a la misma ruta con el mismo secreto de firma.
{
"type": "realtime.member_added",
"timestamp": "2026-07-31T09:00:00Z",
"data": {
"channel": "presence-room-1",
"member_id": "u_42"
}
}
realtime.channel_existenceChannel occupied y vacated: los dos bordes de la vida de un canal, y nada en el intermedio.realtime.presenceMember added y removed. Sigue la identidad, así que la segunda pestaña de una persona no produce nada.realtime.connection_countCuántas conexiones tiene un canal. Requiere que el conteo de conexiones esté habilitado en la app.realtime.cache_channelsUn fallo de caché, que es tu señal para leer el estado actual y publicarlo.realtime.client_eventsUna entrega por evento de cliente, nombrada como él: client-typing llega como realtime.client-typing.
Qué construyen con ellos
Cuatro patrones que necesitan que un servidor sepa qué hacen los clientes.
- 01
Trabajo que solo se ejecuta mientras alguien observa.
Inicia el feed upstream, el poller o el trabajo de renderizado con channel occupied y detenlo con channel vacated. Un dashboard que nadie tiene abierto no cuesta nada mantener activo.
- 02
Una copia del roster en el backend.
Member added y removed mantienen tu propia vista de quién está en una sala, que es de lo que realmente se compone un indicador de disponibilidad de agente o un conteo de asientos. Siguen identidades, así que una persona cerrando una de tres pestañas no produce nada.
- 03
Llenar una caché fría.
Un cliente que se suscribe a un canal de caché sin nada almacenado dispara un fallo en tu endpoint. Lee el estado actual, publícalo, y el cliente que causó el fallo lo recibe, porque ya está suscrito en ese momento.
- 04
Observar el tráfico peer-to-peer.
Los eventos de cliente viajan entre clientes sin tu API. Suscríbete al grupo client-events y tu servidor recibe una copia, con el canal, el id de conexión, y en canales de presencia el id del miembro. Vale la pena saber antes de suscribirte: una señal de alta frecuencia como la posición de un cursor produce una entrega por evento.
Firmado como cualquier otro webhook de Bird.
Las entregas siguen Standard Webhooks, con las cabeceras webhook-id, webhook-timestamp y webhook-signature que verificas contra el secreto de firma del endpoint. El SDK desenvuelve y verifica en una sola llamada. Verifica el cuerpo sin procesar en lugar de una copia re-parseada, ya que re-serializar JSON puede cambiar los bytes firmados, y mantén una rama por defecto para que un nuevo tipo de evento no pueda romper la ruta.
Las garantías de entrega, explicadas con claridad.
Trata estos como notificaciones de cambio en lugar de un registro. Una respuesta no-2xx se reintenta con backoff exponencial hasta por cinco minutos, después de lo cual el evento desaparece: los eventos de Realtime no tienen replay y no aparecen en el log de intentos de entrega del endpoint. Las entregas no están ordenadas y no llevan un acuse por evento, así que ante una entrega retrasada o faltante, lee el estado actual desde la API de estado de canal en lugar de reconstruirlo. Devuelve 2xx tan pronto como hayas aceptado el evento de forma durable y realiza el trabajo después.
Configurado en el dashboard.
Las suscripciones de Realtime se configuran en la página de Webhooks: crea o edita un endpoint, elige una app de Realtime y selecciona los grupos. La app no se puede cambiar después, aunque los grupos sí. Esta es la única parte de la superficie de webhooks de la plataforma que hoy es solo desde el dashboard, y una solicitud a la API pública que incluya un tipo de evento de Realtime es rechazada en lugar de aceptada silenciosamente.
Profundiza en la documentación.
Webhooks en tiempo real lista cada tipo entregado y sus campos de datos. Eventos de cliente cubre el grupo que tú nombras, canales de caché explica qué hacer con un fallo, y webhooks y eventos es el contrato general de la plataforma para endpoints, firmas y rotación de secretos.
Ponlo en práctica.
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
El resto de Realtime
Una app, un par de claves. Explora las demás capacidades.
Descubre cuándo alguien empieza a escuchar.
Apunta un solo endpoint a Realtime y al resto de la plataforma. El mismo sobre, el mismo secreto de firma, la misma llamada de verificación.