Realtime webhooks
Publishing stuurt events naar clients. Webhooks werken in de andere richting: de Realtime edge POST een ondertekend event naar je endpoint wanneer er iets gebeurt op een channel.
Je kunt de channelstatus al on demand opvragen met Channelstatus opvragen. Webhooks zijn de manier om wijzigingen te ontvangen op het moment dat ze plaatsvinden, zonder polling: een client die zich abonneert, een member die zijn laatste tab sluit, een client die een andere client een cursorpositie stuurt.
De vijf eventgroepen
Abonneer je op een of meer eventgroepen:
| Groep | De vraag die het beantwoordt | Wat het oplevert |
|---|---|---|
| realtime.channel_existence | Luistert er iemand? | realtime.channel_occupied, realtime.channel_vacated |
| realtime.presence | Wie is er aanwezig? | realtime.member_added, realtime.member_removed |
| realtime.connection_count | Hoeveel verbindingen? | realtime.connection_count |
| realtime.cache_channels | Heeft dit channel data nodig? | realtime.cache_miss |
| realtime.client_events | Wat sturen clients? | één event per client event, vernoemd naar dat event |
channel_existence rapporteert alleen de twee uiteinden van het bestaan van een channel: channel_occupied wanneer het van nul verbindingen naar één gaat, channel_vacated wanneer de laatste verbinding verdwijnt. Subscribers die er tussenin komen en gaan leveren niets op, wat het de goedkope manier maakt om te weten of publishing zinvol is.
connection_count vereist dat verbindingen tellen is ingeschakeld op de app. Als de instelling is uitgeschakeld, levert de geabonneerde groep geen events op.
Een endpoint abonneren
Open Webhooks, maak een endpoint aan of bewerk er een, en zoek de sectie Realtime events. Selecteer één Realtime app en de groepen die je wilt ontvangen.
Platform-eventabonnementen gelden voor de hele werkruimte, terwijl realtime.*-abonnementen bij één app horen. Je kunt de Realtime app van het endpoint niet meer wijzigen na het aanmaken, maar je kunt de geabonneerde groepen wel bijwerken.
Platform- en Realtime events kunnen een endpoint delen. Eén endpoint kan zich bijvoorbeeld abonneren op email.bounced en realtime.presence. Beide gebruiken het signing secret van het endpoint.
Realtime-groepen zijn momenteel alleen via het dashboard beschikbaar. Een publiek POST /v1/webhooks-verzoek dat een realtime.*-eventtype bevat wordt geweigerd, dus configureer deze abonnementen in het dashboard.
Hoe een delivery eruitziet
Elke POST bevat één event in de standaard webhook-envelope van Bird:
Codevoorbeeld
{
"data": { "channel": "presence-room-1", "member_id": "u_42" },
"timestamp": "2026-07-31T09:00:00Z",
"type": "realtime.member_added"
}type identificeert het geleverde event. De realtime.presence-groep levert bijvoorbeeld realtime.member_added en realtime.member_removed:
| Geleverde type | data-velden |
|---|---|
| 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, plus member_id op een presence channel |
Bij client events kiest de client het eventsuffix. Het triggeren van client-typing levert realtime.client-typing op, en data.event bevat client-typing. Zie Client events.
Een delivery verifiëren
Realtime webhooks volgen Standard Webhooks en bevatten webhook-id-, webhook-timestamp- en webhook-signature-headers. Verifieer ze met het signing secret van het endpoint.
Codevoorbeeld
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;
}
});Verifieer de onbewerkte request body, want het parsen en opnieuw serialiseren van JSON kan de ondertekende bytes wijzigen. Vang onbekende eventtypes op in een default-branch, zodat nieuwe types het endpoint niet breken. Zie Webhook-handtekeningen verifiëren voor het volledige contract.
Presence events tellen members
member_added en member_removed volgen de identiteit, dus ze komen niet één-op-één overeen met verbindingen. Iemand die je app in drie tabs open heeft, is één member:
| Wat er gebeurt | Webhook |
|---|---|
| Eerste tab abonneert | realtime.member_added |
| Tweede tab abonneert | geen |
| Tweede tab sluit | geen |
| Laatste tab sluit | realtime.member_removed |
Gebruik member_removed om te detecteren wanneer een identiteit een channel verlaat. Het beëindigen van een enkele sessie triggert het niet zolang er een andere sessie actief is. Om verbindingen bij te houden, abonneer je op realtime.connection_count. Zie Presence channels.
Delivery-gedrag van Realtime webhooks
Realtime deliveries gebruiken deze regels voor opnieuw proberen en zichtbaarheid:
- Retourneer 2xx direct nadat je het event duurzaam hebt geaccepteerd, en verwerk het vervolgens asynchroon.
- Als je endpoint een niet-2xx-respons retourneert, probeert Realtime het opnieuw met exponentiële backoff gedurende maximaal 5 minuten.
- Realtime events hebben geen replay en verschijnen niet in het delivery-attempts-log van het endpoint.
- Het pauzeren van het endpoint stopt Realtime deliveries samen met al het andere, en het opnieuw inschakelen hervat ze.
Deliveries zijn ongeordend en bieden geen ontvangstbevestiging per event. Behandel ze als wijzigingsnotificaties. Gebruik Channelstatus opvragen om de huidige status op te halen na vertraagde of ontbrekende events.
Volgende stappen
- Client events is de groep waarvan je zelf de eventnamen en payloads bepaalt.
- Cache channels legt uit wat je met realtime.cache_miss kunt doen.
- Webhooks & events behandelt endpoint-instellingen, handtekeningverificatie en secret-rotatie voor elke Bird-webhook.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
Ontdek de mogelijkheidRealtimeVolg het leerpadBuild your first integrationImplementatiegidsSend your first realtime event
Probeer de oefening en ontvang een implementatieoverzicht