Webhooks de Realtime
Publicar envía eventos a los clientes. Los webhooks van en la dirección contraria: el edge de Realtime envía mediante POST un evento firmado a tu endpoint cuando algo ocurre en un canal.
Ya puedes leer el estado de un canal bajo demanda con Consultar el estado de un canal. Los webhooks te permiten enterarte de un cambio en el momento en que sucede, sin sondeo: un cliente que se suscribe, un miembro que cierra su última pestaña, un cliente que envía a otro la posición del cursor.
Los cinco grupos de eventos
Suscríbete a uno o más grupos de eventos:
| Grupo | Pregunta que responde | Qué entrega |
|---|---|---|
| realtime.channel_existence | ¿Hay alguien escuchando? | realtime.channel_occupied, realtime.channel_vacated |
| realtime.presence | ¿Quién está aquí? | realtime.member_added, realtime.member_removed |
| realtime.connection_count | ¿Cuántas conexiones? | realtime.connection_count |
| realtime.cache_channels | ¿Este canal necesita datos? | realtime.cache_miss |
| realtime.client_events | ¿Qué envían los clientes? | un evento por cada evento de cliente, con su mismo nombre |
channel_existence solo informa de los dos extremos de la vida de un canal: channel_occupied cuando pasa de cero conexiones a una, channel_vacated cuando su última conexión se va. Los suscriptores que llegan y se van en el intervalo no producen nada, lo que lo convierte en la forma económica de saber si vale la pena publicar.
connection_count requiere el conteo de conexiones en la app. Si la configuración está desactivada, el grupo suscrito no produce eventos.
Suscribir un endpoint
Abre Webhooks, crea o edita un endpoint y busca la sección Realtime events. Selecciona una app de Realtime y los grupos que quieres recibir.
Las suscripciones a eventos de plataforma se aplican a todo el espacio de trabajo, mientras que las suscripciones de realtime.* pertenecen a una sola app. No puedes cambiar la app de Realtime del endpoint después de crearlo, pero sí puedes actualizar los grupos suscritos.
Los eventos de plataforma y de Realtime pueden compartir un endpoint. Por ejemplo, un endpoint puede suscribirse a email.bounced y realtime.presence. Ambos usan el secreto de firma del endpoint.
Los grupos de Realtime solo se configuran desde el dashboard actualmente. Una solicitud pública de POST /v1/webhooks que incluya un tipo de evento realtime.* se rechaza, así que configura estas suscripciones en el dashboard.
Aspecto de una entrega
Cada POST contiene un evento en el sobre de webhook estándar de Bird:
Ejemplo de código
{
"data": { "channel": "presence-room-1", "member_id": "u_42" },
"timestamp": "2026-07-31T09:00:00Z",
"type": "realtime.member_added"
}type identifica el evento entregado. Por ejemplo, el grupo realtime.presence entrega realtime.member_added y realtime.member_removed:
| type entregado | Campos de data |
|---|---|
| realtime.channel_occupied | channel |
| realtime.channel_vacated | channel |
| realtime.member_added | channel, member_id |
| realtime.member_removed | channel, member_id |
| realtime.connection_count | channel, connection_count |
| realtime.cache_miss | channel |
| realtime.<client event> | channel_name, event, data, connection_id, más member_id en un canal de presencia |
En los eventos de cliente, el cliente elige el sufijo del evento. Activar client-typing produce realtime.client-typing, y data.event contiene client-typing. Consulta Eventos de cliente.
Verificar una entrega
Los webhooks de Realtime siguen Standard Webhooks e incluyen los encabezados webhook-id, webhook-timestamp y webhook-signature. Veríficalos con el secreto de firma del endpoint.
Ejemplo de código
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({
apiKey: process.env.BIRD_API_KEY,
webhooks: { secret: process.env.BIRD_WEBHOOK_SECRET },
});
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_vacated":
stopExpensiveWorkFor(event.data.channel);
break;
case "realtime.member_removed":
markAway(event.data.member_id);
break;
}
});Verifica el cuerpo crudo de la solicitud, porque parsear y re-serializar JSON puede cambiar los bytes firmados. Gestiona los tipos de evento desconocidos en una rama default para que los tipos nuevos no rompan el endpoint. Consulta Verificar firmas de webhook para el contrato completo.
Los eventos de presencia cuentan miembros
member_added y member_removed siguen la identidad, por lo que no se corresponden uno a uno con las conexiones. Alguien con tu app abierta en tres pestañas es un solo miembro:
| Qué sucede | Webhook |
|---|---|
| Primera pestaña se suscribe | realtime.member_added |
| Segunda pestaña se suscribe | ninguno |
| Segunda pestaña se cierra | ninguno |
| Última pestaña se cierra | realtime.member_removed |
Usa member_removed para detectar cuándo una identidad abandona un canal. El cierre de una sola sesión no lo activa mientras otra sesión permanezca. Para rastrear conexiones, suscríbete a realtime.connection_count. Consulta Canales de presencia.
Comportamiento de entrega de webhooks de Realtime
Las entregas de Realtime usan estas reglas de reintentos y visibilidad:
- Devuelve 2xx rápidamente tras aceptar el evento de forma duradera y luego procésalo de manera asíncrona.
- Si tu endpoint devuelve una respuesta distinta de 2xx, Realtime reintenta con retroceso exponencial durante un máximo de 5 minutos.
- Los eventos de Realtime no tienen repetición y no aparecen en el registro de intentos de entrega del endpoint.
- Pausar el endpoint detiene las entregas de Realtime junto con todo lo demás, y reactivarlo las reanuda.
Las entregas no están ordenadas y no proporcionan acuse de recibo por evento. Trátalas como notificaciones de cambio. Usa Consultar el estado de un canal para obtener el estado actual tras eventos retrasados o ausentes.
Próximos pasos
- Eventos de cliente es el grupo cuyos nombres de evento y payloads defines tú.
- Canales de caché explica qué hacer con realtime.cache_miss.
- Webhooks y eventos cubre la configuración de endpoints, la verificación de firmas y la rotación de secretos para cada webhook de Bird.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Explorar la funcionalidadRealtimeSeguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first realtime event
Prueba el ejercicio y obtén un resumen de implementación