Clients abonneren zich en verbreken de verbinding zonder ooit uw backend te bereiken, wat betekent dat uw backend geen idee heeft dat er iemand luistert. Webhooks sluiten die lus: de edge verstuurt een ondertekend event wanneer een kanaal gevuld of leeg raakt, wanneer een lid aankomt of vertrekt, en wanneer een cache-kanaal niets te bieden heeft.
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;
}
});
Stop met betalen voor een publiek van niemand.
Dit is de goedkoopste optimalisatie in Bird Realtime. Een channel-occupied event is het signaal om de dure taak te starten — het marktdata-abonnement, de per-seconde publish-loop; channel-vacated is het signaal om te stoppen. Er wordt niets afgevuurd voor de tussentijds aankomende en vertrekkende abonnees, dus de twee events markeren exact de randen van de levensduur van een kanaal en niets anders.
Vijf groepen. Abonneer u op wat u nodig hebt.
U abonneert zich op een groep; de groep levert de individuele event-types. Eén endpoint kan Realtime-events naast de rest van het platform verwerken, zodat email.bounced en realtime.presence op dezelfde route met hetzelfde signing secret terechtkomen.
{
"type": "realtime.member_added",
"timestamp": "2026-07-31T09:00:00Z",
"data": {
"channel": "presence-room-1",
"member_id": "u_42"
}
}
realtime.channel_existenceChannel occupied en vacated: de twee randen van de levensduur van een kanaal, en niets ertussenin.realtime.presenceMember added en removed. Volgt de identiteit, dus een tweede tabblad van een persoon levert niets op.realtime.connection_countHoeveel verbindingen een kanaal heeft. Vereist dat verbindingstelling is ingeschakeld op de app.realtime.cache_channelsEen cache-miss — uw signaal om de huidige status op te halen en te publiceren.realtime.client_eventsEén delivery per client-event, vernoemd ernaar: client-typing komt binnen als realtime.client-typing.
Wat mensen ermee bouwen
Vier patronen waarbij een server moet weten wat de clients doen.
- 01
Werk dat alleen draait terwijl er gekeken wordt.
Start de upstream-feed, de poller of de rendertaak bij channel occupied en sluit deze af bij channel vacated. Een dashboard dat niemand open heeft, kost niets om live te houden.
- 02
Een backend-kopie van de ledenlijst.
Member added en removed houden uw eigen overzicht bij van wie er in een ruimte is — precies waar een beschikbaarheidsindicator voor agents of een stoeltelling op is gebouwd. Ze volgen identiteiten, dus een persoon die één van drie tabbladen sluit, levert niets op.
- 03
Een koude cache vullen.
Een client die zich abonneert op een cache-kanaal zonder gecachte data triggert een miss op uw endpoint. Lees de huidige status, publiceer deze, en de client die de miss veroorzaakte ontvangt het — want die is op dat moment al geabonneerd.
- 04
Peer-to-peer verkeer monitoren.
Client-events reizen tussen clients zonder uw API. Abonneer u op de client-events-groep en uw server ontvangt een kopie, met het kanaal, het connection-id en op presence-kanalen het member-id. Goed om te weten voordat u zich abonneert: een hoogfrequent signaal zoals een cursorpositie levert één delivery per event op.
Ondertekend zoals elke andere Bird-webhook.
Deliveries volgen Standard Webhooks, met webhook-id, webhook-timestamp en webhook-signature headers die u verifieert tegen het signing secret van het endpoint. De SDK unwrapt en verifieert in één aanroep. Verifieer de ruwe body in plaats van een opnieuw geparsete kopie, want het opnieuw serialiseren van JSON kan de ondertekende bytes wijzigen, en houd een default-branch aan zodat een nieuw event-type de route niet kan breken.
De leveringsgaranties, helder uitgelegd.
Behandel deze als wijzigingsmeldingen in plaats van een logboek. Een niet-2xx-respons wordt opnieuw geprobeerd met exponentiële backoff gedurende maximaal vijf minuten, waarna het event verdwijnt: Realtime-events hebben geen replay en verschijnen niet in het delivery-attempts-log van het endpoint. Deliveries zijn ongeordend en hebben geen per-event-ontvangstbevestiging, dus lees na een vertraagde of ontbrekende delivery de huidige status via de channel-state API in plaats van deze te reconstrueren. Retourneer 2xx zodra u het event duurzaam hebt geaccepteerd en doe het werk daarna.
Geconfigureerd in het dashboard.
Realtime-abonnementen worden ingesteld op de Webhooks-pagina: maak een endpoint aan of bewerk er een, kies één Realtime-app en selecteer de groepen. De app kan achteraf niet worden gewijzigd, de groepen wel. Dit is het enige onderdeel van het webhook-oppervlak van het platform dat momenteel alleen via het dashboard beschikbaar is, en een publiek API-verzoek dat een realtime event-type bevat wordt geweigerd in plaats van stilzwijgend geaccepteerd.
Dieper de docs in.
Realtime webhooks toont elk geleverd type en de bijbehorende datavelden. Client events behandelt de groep die u zelf benoemt, cache channels legt uit wat u met een miss doet, en webhooks and events is het platformbrede contract voor endpoints, signatures en secret-rotatie.
Breng het in de praktijk.
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
De rest van Realtime
Eén app, één sleutelpaar. Ontdek de andere mogelijkheden.
Ontdek wanneer iemand begint te luisteren.
Richt één endpoint op Realtime en de rest van het platform. Dezelfde envelope, hetzelfde ondertekeningsgeheim, dezelfde verificatie-aanroep.