Realtime-Webhooks
Publishing geht raus. Webhooks kommen zurück.
Clients abonnieren und trennen die Verbindung, ohne jemals Ihr Backend zu erreichen – Ihr Backend hat also keine Ahnung, dass jemand zuhört. Webhooks schließen diese Lücke: Die Edge sendet ein signiertes Event, wenn ein Kanal sich füllt oder leert, wenn ein Mitglied eintritt oder geht und wenn ein Cache-Kanal nichts auszuliefern hat.
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;
}
});
Täglich vertraut von Teams, die erstklassige Software entwickeln
Weitere Kundenberichte lesenHören Sie auf, für ein Publikum von null zu bezahlen.
Das ist die günstigste Optimierung in Bird Realtime. Ein channel-occupied-Event ist das Signal, den teuren Job zu starten – das Marktdaten-Abo, die Publish-Schleife im Sekundentakt; channel-vacated ist das Signal, ihn zu stoppen. Für die Subscriber, die dazwischen kommen und gehen, wird nichts ausgelöst – die beiden Events markieren exakt die Grenzen eines Kanal-Lebenszyklus und sonst nichts.
Fünf Gruppen. Abonnieren Sie, was Sie brauchen.
Sie abonnieren eine Gruppe; die Gruppe liefert die einzelnen Event-Typen. Ein Endpunkt kann Realtime-Events zusammen mit dem Rest der Plattform empfangen – email.bounced und realtime.presence können auf derselben Route mit demselben Signing-Secret landen.
{
"type": "realtime.member_added",
"timestamp": "2026-07-31T09:00:00Z",
"data": {
"channel": "presence-room-1",
"member_id": "u_42"
}
}
realtime.channel_existenceChannel occupied und vacated: die beiden Grenzen eines Kanal-Lebenszyklus, und nichts dazwischen.realtime.presenceMember added und removed. Folgt der Identität – ein zweiter Tab derselben Person erzeugt nichts.realtime.connection_countWie viele Verbindungen ein Kanal hält. Erfordert aktiviertes Connection-Counting in der App.realtime.cache_channelsEin Cache-Miss – Ihr Signal, den aktuellen Zustand zu lesen und zu veröffentlichen.realtime.client_eventsEine Zustellung pro Client-Event, benannt nach dem Event: client-typing kommt als realtime.client-typing an.
Was damit gebaut wird
Vier Muster, bei denen ein Server wissen muss, was die Clients tun.
- 01
Arbeit, die nur läuft, wenn jemand zuschaut.
Starten Sie den Upstream-Feed, den Poller oder den Render-Job bei channel occupied und stoppen Sie ihn bei channel vacated. Ein Dashboard, das niemand geöffnet hat, kostet nichts im laufenden Betrieb.
- 02
Eine Backend-Kopie der Teilnehmerliste.
Member added und removed halten Ihre eigene Sicht darauf, wer sich in einem Raum befindet – und genau daraus besteht ein Agenten-Verfügbarkeitsindikator oder ein Sitzplatzzähler. Sie folgen Identitäten – wenn eine Person einen von drei Tabs schließt, passiert nichts.
- 03
Einen kalten Cache füllen.
Ein Client, der einen Cache-Kanal ohne gecachte Daten abonniert, löst einen Miss auf Ihrem Endpunkt aus. Lesen Sie den aktuellen Zustand, veröffentlichen Sie ihn, und der Client, der den Miss verursacht hat, empfängt ihn – denn er ist zu diesem Zeitpunkt bereits abonniert.
- 04
Den Peer-to-Peer-Verkehr beobachten.
Client-Events reisen zwischen Clients, ohne Ihre API zu berühren. Abonnieren Sie die Client-Events-Gruppe, und Ihr Server erhält eine Kopie – mit dem Kanal, der Connection-ID und bei Presence-Kanälen der Member-ID. Wichtig zu wissen, bevor Sie abonnieren: Ein hochfrequentes Signal wie eine Cursorposition erzeugt eine Zustellung pro Event.
Signiert wie jeder andere Bird-Webhook.
Zustellungen folgen Standard Webhooks, mit den Headern webhook-id, webhook-timestamp und webhook-signature, die Sie gegen das Signing-Secret des Endpunkts verifizieren. Das SDK entpackt und verifiziert in einem Aufruf. Verifizieren Sie den Roh-Body statt einer erneut geparsten Kopie, da das erneute Serialisieren von JSON die signierten Bytes verändern kann, und behalten Sie einen Default-Branch bei, damit ein neuer Event-Typ die Route nicht brechen kann.
Die Zustellungsgarantien, klar formuliert.
Behandeln Sie diese als Änderungsbenachrichtigungen, nicht als Protokoll. Eine Nicht-2xx-Antwort wird mit exponentiellem Backoff bis zu fünf Minuten lang erneut versucht; danach ist das Event weg: Realtime-Events haben kein Replay und erscheinen nicht im Delivery-Attempts-Log des Endpunkts. Zustellungen sind ungeordnet und enthalten keine Empfangsbestätigung pro Event – lesen Sie nach einer verzögerten oder fehlenden Zustellung den aktuellen Zustand über die Channel-State-API, statt ihn zu rekonstruieren. Geben Sie 2xx zurück, sobald Sie das Event dauerhaft angenommen haben, und erledigen Sie die Arbeit danach.
Im Dashboard konfiguriert.
Realtime-Abonnements werden auf der Webhooks-Seite eingerichtet: Erstellen oder bearbeiten Sie einen Endpunkt, wählen Sie eine Realtime-App und die Gruppen. Die App kann danach nicht mehr geändert werden, die Gruppen schon. Das ist der einzige Teil der Webhook-Oberfläche der Plattform, der derzeit nur im Dashboard verfügbar ist – ein öffentlicher API-Request mit einem Realtime-Event-Typ wird abgelehnt, nicht stillschweigend akzeptiert.
Mehr dazu in der Dokumentation.
Realtime-Webhooks listet jeden zugestellten Typ und seine Datenfelder. Client-Events behandelt die Gruppe, die Sie selbst benennen, Cache-Kanäle erklärt, was bei einem Miss zu tun ist, und Webhooks und Events ist der plattformweite Vertrag für Endpunkte, Signaturen und Secret-Rotation.
In die Praxis umsetzen.
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Der Rest von Realtime
Eine App, ein Schlüsselpaar. Entdecken Sie die weiteren Funktionen.
Erfahren Sie, wenn jemand anfängt zuzuhören.
Richten Sie einen Endpunkt auf Realtime und den Rest der Plattform. Dasselbe Envelope, dasselbe Signing-Secret, derselbe Verifizierungsaufruf.