Realtime-Webhooks

Publishing sendet Events an Clients. Webhooks laufen in die andere Richtung: Der Realtime-Edge sendet per POST ein signiertes Event an Ihren Endpoint, wenn auf einem Channel etwas passiert.

Den Channel-Status können Sie bereits bei Bedarf mit Channel-Status abfragen lesen. Webhooks informieren Sie über eine Änderung, sobald sie eintritt, ohne Polling: ein Client abonniert, ein Mitglied schließt seinen letzten Tab, ein Client sendet einem anderen eine Cursorposition.

Die fünf Event-Gruppen

Abonnieren Sie eine oder mehrere Event-Gruppen:

Gruppe	Welche Frage sie beantwortet	Was sie liefert
realtime.channel_existence	Hört jemand zu?	realtime.channel_occupied, realtime.channel_vacated
realtime.presence	Wer ist da?	realtime.member_added, realtime.member_removed
realtime.connection_count	Wie viele Verbindungen?	realtime.connection_count
realtime.cache_channels	Braucht dieser Channel Daten?	realtime.cache_miss
realtime.client_events	Was senden Clients?	ein Event pro Client-Event, nach diesem benannt

channel_existence meldet nur die beiden Ränder im Lebenszyklus eines Channels: channel_occupied, wenn er von null Verbindungen auf eine wechselt, channel_vacated, wenn die letzte Verbindung wegfällt. Abonnenten, die dazwischen kommen und gehen, erzeugen nichts – damit ist es die günstige Methode um festzustellen, ob sich das Publishing lohnt.

connection_count erfordert Verbindungszählung in der App. Ist die Einstellung deaktiviert, erzeugt die abonnierte Gruppe keine Events.

Einen Endpoint abonnieren

Öffnen Sie Webhooks, erstellen oder bearbeiten Sie einen Endpoint und suchen Sie den Abschnitt Realtime events. Wählen Sie eine Realtime-App und die gewünschten Gruppen aus.

Plattform-Event-Abonnements gelten workspace-weit, während realtime.*-Abonnements zu einer einzelnen App gehören. Sie können die Realtime-App des Endpoints nach dem Erstellen nicht mehr ändern, aber die abonnierten Gruppen aktualisieren.

Plattform- und Realtime-Events können sich einen Endpoint teilen. Ein Endpoint kann zum Beispiel email.bounced und realtime.presence abonnieren. Beide verwenden das Signing-Secret des Endpoints.

Realtime-Gruppen lassen sich derzeit nur im Dashboard konfigurieren. Ein öffentlicher POST /v1/webhooks-Request, der einen realtime.*-Event-Typ enthält, wird abgelehnt. Richten Sie diese Abonnements daher im Dashboard ein.

Wie eine Zustellung aussieht

Jeder POST enthält ein Event im Standard-Webhook-Envelope von Bird:

Codebeispiel

{
  "data": { "channel": "presence-room-1", "member_id": "u_42" },
  "timestamp": "2026-07-31T09:00:00Z",
  "type": "realtime.member_added"
}

type identifiziert das zugestellte Event. Zum Beispiel liefert die Gruppe realtime.presence die Events realtime.member_added und realtime.member_removed:

Zugestellter type	data-Felder
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 auf einem Presence-Channel

Bei Client-Events wählt der Client das Event-Suffix. Das Auslösen von client-typing erzeugt realtime.client-typing, und data.event enthält client-typing. Siehe Client-Events.

Eine Zustellung verifizieren

Realtime-Webhooks folgen Standard Webhooks und enthalten die Header webhook-id, webhook-timestamp und webhook-signature. Verifizieren Sie sie mit dem Signing-Secret des Endpoints.

Codebeispiel

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;
  }
});

Verifizieren Sie den rohen Request-Body, da das Parsen und erneute Serialisieren von JSON die signierten Bytes verändern kann. Behandeln Sie unbekannte Event-Typen in einem default-Zweig, damit neue Typen den Endpoint nicht beeinträchtigen. Siehe Webhook-Signaturen verifizieren für den vollständigen Vertrag.

Presence-Events zählen Mitglieder

member_added und member_removed folgen der Identität und stimmen daher nicht eins zu eins mit Verbindungen überein. Jemand, der Ihre App in drei Tabs geöffnet hat, ist ein Mitglied:

Was passiert	Webhook
Erster Tab abonniert	realtime.member_added
Zweiter Tab abonniert	keiner
Zweiter Tab schließt	keiner
Letzter Tab schließt	realtime.member_removed

Verwenden Sie member_removed, um zu erkennen, wann eine Identität einen Channel verlässt. Das Beenden einer einzelnen Sitzung löst das Event nicht aus, solange eine andere Sitzung bestehen bleibt. Um Verbindungen zu verfolgen, abonnieren Sie realtime.connection_count. Siehe Presence-Channels.

Zustellverhalten von Realtime-Webhooks

Realtime-Zustellungen folgen diesen Regeln für Wiederholung und Sichtbarkeit:

Geben Sie 2xx umgehend zurück, nachdem Sie das Event dauerhaft angenommen haben, und verarbeiten Sie es dann asynchron.
Gibt Ihr Endpoint eine Nicht-2xx-Antwort zurück, versucht Realtime es mit exponentiellem Backoff bis zu 5 Minuten lang erneut.
Realtime-Events haben kein Replay und erscheinen nicht im Zustellversuch-Log des Endpoints.
Wird der Endpoint pausiert, stoppt das auch die Realtime-Zustellungen zusammen mit allem anderen. Beim erneuten Aktivieren werden sie fortgesetzt.

Zustellungen sind ungeordnet und bieten keine Empfangsbestätigung pro Event. Behandeln Sie sie als Änderungsbenachrichtigungen. Verwenden Sie Channel-Status abfragen, um den aktuellen Status nach verzögerten oder fehlenden Events abzurufen.

Nächste Schritte

Client-Events ist die Gruppe, deren Event-Namen und Payloads Sie selbst definieren.
Cache-Channels erklärt, was Sie mit realtime.cache_miss tun können.
Webhooks & Events behandelt Endpoint-Einrichtung, Signaturverifizierung und Secret-Rotation für jeden Bird-Webhook.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Explore the capabilityRealtime Follow the learning pathBuild your first integration Implementation guideSend your first realtime event

Try the practice and get an implementation brief