Webhooki Realtime
Publikowanie wysyła zdarzenia do klientów. Webhooki działają w odwrotnym kierunku: warstwa brzegowa Realtime wysyła POSTem podpisane zdarzenie na Twój endpoint, gdy coś się dzieje na kanale.
Stan kanału możesz już odczytać na żądanie za pomocą Odpytywania stanu kanału. Webhooki informują Cię o zmianach w momencie ich wystąpienia, bez odpytywania: subskrypcja klienta, zamknięcie ostatniej karty przez członka, wysłanie pozycji kursora między klientami.
Pięć grup zdarzeń
Zasubskrybuj jedną lub więcej grup zdarzeń:
| Grupa | Na jakie pytanie odpowiada | Co dostarcza |
|---|---|---|
| realtime.channel_existence | Czy ktoś nasłuchuje? | realtime.channel_occupied, realtime.channel_vacated |
| realtime.presence | Kto tu jest? | realtime.member_added, realtime.member_removed |
| realtime.connection_count | Ile połączeń? | realtime.connection_count |
| realtime.cache_channels | Czy ten kanał potrzebuje danych? | realtime.cache_miss |
| realtime.client_events | Co wysyłają klienci? | jedno zdarzenie na zdarzenie klienckie, nazwane tak jak ono |
channel_existence raportuje tylko dwa krańce życia kanału: channel_occupied, gdy liczba połączeń rośnie z zera do jednego, i channel_vacated, gdy ostatnie połączenie znika. Subskrybenci dołączający i odchodzący pomiędzy nie generują niczego, co czyni tę grupę tanim sposobem na sprawdzenie, czy publikowanie ma sens.
connection_count wymaga włączonego zliczania połączeń w aplikacji. Jeśli to ustawienie jest wyłączone, zasubskrybowana grupa nie generuje zdarzeń.
Subskrybuj endpoint
Otwórz Webhooki, utwórz lub edytuj endpoint i znajdź sekcję Realtime events. Wybierz jedną aplikację Realtime i grupy do odbierania.
Subskrypcje zdarzeń platformy obowiązują w całym obszarze roboczym, natomiast subskrypcje realtime.* należą do jednej aplikacji. Nie możesz zmienić aplikacji Realtime endpointu po jego utworzeniu, ale możesz aktualizować zasubskrybowane grupy.
Zdarzenia platformy i Realtime mogą współdzielić endpoint. Na przykład jeden endpoint może subskrybować email.bounced i realtime.presence. Oba używają sekretu podpisywania endpointu.
Grupy Realtime są obecnie dostępne tylko z poziomu dashboardu. Publiczne żądanie POST /v1/webhooks zawierające typ zdarzenia realtime.* zostanie odrzucone, więc konfiguruj te subskrypcje w dashboardzie.
Jak wygląda dostarczenie
Każdy POST zawiera jedno zdarzenie w standardowej kopercie webhookowej Bird:
Przykład kodu
{
"data": { "channel": "presence-room-1", "member_id": "u_42" },
"timestamp": "2026-07-31T09:00:00Z",
"type": "realtime.member_added"
}type identyfikuje dostarczone zdarzenie. Na przykład grupa realtime.presence dostarcza realtime.member_added i realtime.member_removed:
| Dostarczony type | Pola data |
|---|---|
| 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 na kanale z obecnością |
W przypadku zdarzeń klienckich to klient wybiera sufiks zdarzenia. Wywołanie client-typing generuje realtime.client-typing, a data.event zawiera client-typing. Zobacz Zdarzenia klienckie.
Weryfikacja dostarczenia
Webhooki Realtime są zgodne ze Standard Webhooks i zawierają nagłówki webhook-id, webhook-timestamp i webhook-signature. Weryfikuj je za pomocą sekretu podpisywania endpointu.
Przykład kodu
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;
}
});Weryfikuj surowe ciało żądania, ponieważ parsowanie i ponowna serializacja JSON mogą zmienić podpisane bajty. Obsługuj nieznane typy zdarzeń w gałęzi default, aby nowe typy nie psuły endpointu. Zobacz Weryfikacja podpisów webhooków po pełny kontrakt.
Zdarzenia obecności zliczają członków
member_added i member_removed podążają za tożsamością, więc nie odpowiadają jeden do jednego połączeniom. Ktoś z Twoją aplikacją otwartą w trzech kartach to jeden członek:
| Co się dzieje | Webhook |
|---|---|
| Pierwsza karta subskrybuje | realtime.member_added |
| Druga karta subskrybuje | brak |
| Druga karta się zamyka | brak |
| Ostatnia karta się zamyka | realtime.member_removed |
Użyj member_removed, aby wykryć, kiedy tożsamość opuszcza kanał. Zakończenie pojedynczej sesji nie wyzwala tego zdarzenia, dopóki inna sesja trwa. Aby śledzić połączenia, zasubskrybuj realtime.connection_count. Zobacz Kanały z obecnością.
Zachowanie dostarczania webhooków Realtime
Dostarczenia Realtime stosują następujące zasady ponownych prób i widoczności:
- Zwróć 2xx natychmiast po trwałym przyjęciu zdarzenia, a następnie przetwórz je asynchronicznie.
- Jeśli Twój endpoint zwróci odpowiedź inną niż 2xx, Realtime ponawia próby z wykładniczym wycofaniem przez maksymalnie 5 minut.
- Zdarzenia Realtime nie mają funkcji powtórki i nie pojawiają się w logu prób dostarczenia endpointu.
- Wstrzymanie endpointu zatrzymuje dostarczenia Realtime wraz ze wszystkim innym, a ponowne włączenie wznawia je.
Dostarczenia nie mają ustalonej kolejności i nie zapewniają potwierdzenia poszczególnych zdarzeń. Traktuj je jako powiadomienia o zmianach. Użyj Odpytywania stanu kanału, aby pobrać aktualny stan po opóźnionych lub utraconych zdarzeniach.
Następne kroki
- Zdarzenia klienckie to grupa, w której sam definiujesz nazwy zdarzeń i ich ładunki.
- Kanały z pamięcią podręczną wyjaśnia, co zrobić z realtime.cache_miss.
- Webhooki i zdarzenia obejmuje konfigurację endpointu, weryfikację podpisów i rotację sekretów dla każdego webhooka Bird.
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Poznaj możliwościRealtimePodążaj ścieżką naukiBuild your first integrationPrzewodnik wdrożeniowySend your first realtime event
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy