Webhooks en temps réel
La publication part. Les webhooks reviennent.
Les clients s'abonnent et se déconnectent sans jamais atteindre votre backend, ce qui signifie que votre backend ignore si quelqu'un écoute. Les webhooks comblent ce vide : la périphérie envoie un événement signé lorsqu'un canal se remplit ou se vide, lorsqu'un membre arrive ou part, et lorsqu'un canal de cache n'a rien à 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;
}
});
Arrêtez de payer pour une audience inexistante.
C'est l'optimisation la moins coûteuse de Bird Realtime. Un événement channel-occupied est le signal pour lancer le travail coûteux — l'abonnement aux données de marché, la boucle de publication par seconde ; channel-vacated est le signal pour l'arrêter. Rien ne se déclenche pour les abonnés qui arrivent et partent entre-temps : les deux événements marquent exactement les limites de la vie d'un canal, et rien d'autre.
Cinq groupes. Abonnez-vous à ce dont vous avez besoin.
Vous vous abonnez à un groupe ; le groupe délivre les types d'événements individuels. Un seul endpoint peut recevoir les événements Realtime aux côtés du reste de la plateforme : email.bounced et realtime.presence peuvent arriver sur la même route avec le même secret de signature.
{
"type": "realtime.member_added",
"timestamp": "2026-07-31T09:00:00Z",
"data": {
"channel": "presence-room-1",
"member_id": "u_42"
}
}
realtime.channel_existenceChannel occupied et vacated : les deux limites de la vie d'un canal, et rien entre les deux.realtime.presenceMembre ajouté et supprimé. Suit l'identité : le deuxième onglet d'une personne ne produit rien.realtime.connection_countNombre de connexions d'un canal. Nécessite l'activation du comptage de connexions sur l'application.realtime.cache_channelsUn défaut de cache, signal pour lire l'état actuel et le publier.realtime.client_eventsUne livraison par événement client, nommée d'après lui : client-typing arrive en tant que realtime.client-typing.
Ce que les gens construisent avec
Quatre patterns qui nécessitent qu'un serveur sache ce que font les clients.
- 01
Du travail qui ne tourne que sous surveillance.
Démarrez le flux amont, le poller ou le job de rendu sur channel occupied et arrêtez-le sur channel vacated. Un tableau de bord que personne n'a ouvert ne coûte rien à maintenir actif.
- 02
Une copie backend du roster.
Les événements member added et removed maintiennent votre propre vue de qui est dans une salle — c'est exactement ce dont un indicateur de disponibilité d'agent ou un compteur de sièges est fait. Ils suivent les identités : une personne fermant un de ses trois onglets ne produit rien.
- 03
Remplir un cache froid.
Un client s'abonnant à un canal de cache vide déclenche un défaut sur votre endpoint. Lisez l'état actuel, publiez-le, et le client à l'origine du défaut le reçoit, car il est déjà abonné à ce moment-là.
- 04
Surveiller le trafic pair-à-pair.
Les événements client circulent entre clients sans passer par votre API. Abonnez-vous au groupe client-events et votre serveur reçoit une copie, avec le canal, l'identifiant de connexion, et sur les canaux de présence, l'identifiant du membre. À savoir avant de vous abonner : un signal haute fréquence comme une position de curseur produit une livraison par événement.
Signé comme tout autre webhook Bird.
Les livraisons suivent le standard Standard Webhooks, avec les en-têtes webhook-id, webhook-timestamp et webhook-signature que vous vérifiez avec le secret de signature de l'endpoint. Le SDK décompresse et vérifie en un seul appel. Vérifiez le corps brut plutôt qu'une copie re-parsée, car la re-sérialisation du JSON peut modifier les octets signés, et conservez une branche par défaut pour qu'un nouveau type d'événement ne casse pas la route.
Les garanties de livraison, clairement énoncées.
Traitez-les comme des notifications de changement plutôt qu'un registre. Une réponse non-2xx est retentée avec un backoff exponentiel pendant cinq minutes maximum, après quoi l'événement est perdu : les événements Realtime n'ont pas de rejeu et n'apparaissent pas dans le journal des tentatives de livraison de l'endpoint. Les livraisons ne sont pas ordonnées et ne portent pas d'accusé de réception par événement : après une livraison retardée ou manquante, lisez l'état actuel via l'API channel-state plutôt que de le reconstituer. Renvoyez 2xx dès que vous avez accepté durablement l'événement et effectuez le traitement ensuite.
Configuré dans le tableau de bord.
Les abonnements Realtime se configurent sur la page Webhooks : créez ou modifiez un endpoint, choisissez une application Realtime et sélectionnez les groupes. L'application ne peut pas être changée ensuite, mais les groupes si. C'est la seule partie de la surface webhook de la plateforme qui est uniquement accessible via le tableau de bord aujourd'hui ; une requête API publique incluant un type d'événement Realtime est rejetée plutôt qu'acceptée silencieusement.
Approfondissez dans la documentation.
Webhooks Realtime liste chaque type livré et ses champs de données. Client events couvre le groupe que vous nommez vous-même, cache channels explique quoi faire avec un défaut, et webhooks and events est le contrat global de la plateforme pour les endpoints, les signatures et la rotation des secrets.
Mettez-le en pratique.
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Le reste de Realtime
Une application, une paire de clés. Explorez les autres fonctionnalités.
Découvrez quand quelqu'un commence à écouter.
Dirigez un seul endpoint vers Realtime et le reste de la plateforme. Même enveloppe, même secret de signature, même appel de vérification.