Webhooki w czasie rzeczywistym

Publikowanie wychodzi. Webhooki wracają.

Rozpocznij Przeczytaj przewodnik po webhookach

Klienci subskrybują i rozłączają się, nigdy nie docierając do Twojego backendu — a to oznacza, że Twój backend nie wie, że ktokolwiek nasłuchuje. Webhooki zamykają tę pętlę: edge wysyła podpisane zdarzenie, gdy kanał się zapełnia lub pustoszeje, gdy członek dołącza lub odchodzi i gdy kanał cache nie ma czego dostarczyć.

webhooks.ts

signed

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

webhooks.ts

signed

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

Przestań płacić za publiczność, której nie ma.

To najtańsza optymalizacja w Bird Realtime. Zdarzenie channel-occupied to sygnał do uruchomienia kosztownego zadania — subskrypcji danych rynkowych, pętli publikacji co sekundę; channel-vacated to sygnał do zatrzymania. Nic nie jest wyzwalane dla subskrybentów dołączających i odchodzących pomiędzy, więc te dwa zdarzenia wyznaczają dokładnie krawędzie życia kanału i nic więcej.

Pięć grup. Subskrybuj to, czego potrzebujesz.

Subskrybujesz grupę; grupa dostarcza poszczególne typy zdarzeń. Jeden endpoint może obsługiwać zdarzenia Realtime obok reszty platformy, więc email.bounced i realtime.presence mogą trafiać na tę samą trasę z tym samym kluczem podpisu.

POST /webhooks/bird

realtime.member_added

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

realtime.channel_existenceChannel occupied i vacated: dwie krawędzie życia kanału i nic pomiędzy.
realtime.presenceDodanie i usunięcie członka. Śledzi tożsamość, więc druga karta tej samej osoby nie generuje niczego.
realtime.connection_countIle połączeń utrzymuje kanał. Wymaga włączonego liczenia połączeń w aplikacji.
realtime.cache_channelsChybienie cache — sygnał, by odczytać bieżący stan i opublikować go.
realtime.client_eventsJedno dostarczenie na zdarzenie klienta, nazwane na jego podstawie: client-typing trafia jako realtime.client-typing.

Co ludzie z nimi budują

Cztery wzorce, w których serwer musi wiedzieć, co robią klienci.

01
Praca uruchamiana tylko, gdy ktoś patrzy.
Uruchom feed upstream, poller lub zadanie renderowania przy channel occupied i wyłącz przy channel vacated. Dashboard, którego nikt nie ma otwartego, nic nie kosztuje w utrzymaniu.
02
Kopia listy obecności po stronie backendu.
Zdarzenia dodania i usunięcia członka utrzymują Twój własny widok tego, kto jest w pokoju — a właśnie z tego składa się wskaźnik dostępności agenta czy licznik miejsc. Śledzą tożsamości, więc zamknięcie jednej z trzech kart przez osobę nie generuje niczego.
03
Wypełnianie zimnego cache.
Klient subskrybujący kanał cache bez danych w cache wywołuje chybienie na Twoim endpoincie. Odczytaj bieżący stan, opublikuj go, a klient, który wywołał chybienie, otrzyma dane — bo w tym momencie jest już zasubskrybowany.
04
Obserwowanie ruchu peer-to-peer.
Zdarzenia klientów podróżują między klientami bez Twojego API. Subskrybuj grupę client-events, a Twój serwer otrzyma kopię — z kanałem, identyfikatorem połączenia, a na kanałach presence także identyfikatorem członka. Warto wiedzieć przed subskrypcją: sygnał o wysokiej częstotliwości, jak pozycja kursora, generuje jedno dostarczenie na zdarzenie.

Podpisane jak każdy inny webhook Bird.

Dostarczenia są zgodne ze Standard Webhooks, z nagłówkami webhook-id, webhook-timestamp i webhook-signature, które weryfikujesz kluczem podpisu endpointa. SDK rozpakowuje i weryfikuje w jednym wywołaniu. Weryfikuj surowe ciało żądania, a nie ponownie sparsowaną kopię — ponowna serializacja JSON może zmienić podpisane bajty. Zachowaj domyślną gałąź, aby nowy typ zdarzenia nie mógł zepsuć trasy.

Gwarancje dostarczenia, ujęte wprost.

Traktuj je jako powiadomienia o zmianach, a nie jako rejestr. Odpowiedź inna niż 2xx jest ponawiana z wykładniczym wycofywaniem przez maksymalnie pięć minut, po czym zdarzenie jest tracone: zdarzenia Realtime nie mają replay i nie pojawiają się w logu prób dostarczenia endpointa. Dostarczenia są nieuporządkowane i nie zawierają potwierdzenia per zdarzenie, więc po opóźnionym lub brakującym dostarczeniu odczytaj bieżący stan z API stanu kanału, zamiast go rekonstruować. Zwróć 2xx, gdy trwale przyjmiesz zdarzenie, a pracę wykonaj później.

Konfiguracja w dashboardzie.

Subskrypcje Realtime konfiguruje się na stronie Webhooks: utwórz lub edytuj endpoint, wybierz jedną aplikację Realtime i zaznacz grupy. Aplikacji nie można potem zmienić, ale grupy — tak. To jedyna część interfejsu webhooków platformy, która dziś jest dostępna wyłącznie w dashboardzie; żądanie API zawierające typ zdarzenia Realtime zostanie odrzucone, a nie cicho zaakceptowane.

Zanurz się głębiej w dokumentacji.

Webhooki Realtime wymieniają każdy dostarczany typ i jego pola danych. Zdarzenia klientów obejmują grupę, którą sam nazywasz, kanały cache wyjaśniają, co zrobić z chybieniem, a webhooki i zdarzenia to ogólnoplatformowy kontrakt dla endpointów, podpisów i rotacji kluczy.