Webhook Realtime
La pubblicazione invia eventi ai client. I webhook funzionano nella direzione opposta: l'edge Realtime invia tramite POST un evento firmato al tuo endpoint quando qualcosa accade su un canale.
Puoi già leggere lo stato di un canale on demand con Interrogare lo stato del canale. I webhook ti permettono di ricevere notifiche su un cambiamento nel momento in cui avviene, senza polling: un client che si iscrive, un membro che chiude la sua ultima scheda, un client che invia a un altro la posizione del cursore.
I cinque gruppi di eventi
Iscriviti a uno o più gruppi di eventi:
| Gruppo | Domanda a cui risponde | Cosa consegna |
|---|---|---|
| realtime.channel_existence | C'è qualcuno in ascolto? | realtime.channel_occupied, realtime.channel_vacated |
| realtime.presence | Chi è presente? | realtime.member_added, realtime.member_removed |
| realtime.connection_count | Quante connessioni? | realtime.connection_count |
| realtime.cache_channels | Questo canale ha bisogno di dati? | realtime.cache_miss |
| realtime.client_events | Cosa stanno inviando i client? | un evento per ogni evento client, con lo stesso nome |
channel_existence segnala solo i due estremi della vita di un canale: channel_occupied quando passa da zero connessioni a una, channel_vacated quando l'ultima connessione se ne va. Gli iscritti che arrivano e partono nel frattempo non producono nulla, il che lo rende il modo economico per sapere se vale la pena pubblicare.
connection_count richiede il conteggio delle connessioni sull'app. Se l'impostazione è disabilitata, il gruppo sottoscritto non produce eventi.
Iscrivere un endpoint
Apri Webhooks, crea o modifica un endpoint e trova la sezione Realtime events. Seleziona un'app Realtime e i gruppi da ricevere.
Le iscrizioni agli eventi della piattaforma si applicano a tutto lo spazio di lavoro, mentre le iscrizioni realtime.* appartengono a una singola app. Non puoi cambiare l'app Realtime dell'endpoint dopo averlo creato, ma puoi aggiornare i gruppi sottoscritti.
Gli eventi della piattaforma e quelli Realtime possono condividere un endpoint. Ad esempio, un endpoint può iscriversi a email.bounced e realtime.presence. Entrambi usano il signing secret dell'endpoint.
I gruppi Realtime al momento sono configurabili solo dalla dashboard. Una richiesta POST /v1/webhooks pubblica che include un tipo di evento realtime.* viene rifiutata: configura queste iscrizioni dalla dashboard.
Aspetto di una consegna
Ogni POST contiene un evento nell'envelope webhook standard di Bird:
Esempio di codice
{
"data": { "channel": "presence-room-1", "member_id": "u_42" },
"timestamp": "2026-07-31T09:00:00Z",
"type": "realtime.member_added"
}type identifica l'evento consegnato. Ad esempio, il gruppo realtime.presence consegna realtime.member_added e realtime.member_removed:
| type consegnato | Campi 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, più member_id su un canale presence |
Per gli eventi client, il client sceglie il suffisso dell'evento. Attivare client-typing produce realtime.client-typing, e data.event contiene client-typing. Vedi Eventi client.
Verificare una consegna
I webhook Realtime seguono lo standard Standard Webhooks e includono gli header webhook-id, webhook-timestamp e webhook-signature. Verificali con il signing secret dell'endpoint.
Esempio di codice
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;
}
});Verifica il corpo grezzo della richiesta, perché il parsing e la ri-serializzazione di JSON possono alterare i byte firmati. Gestisci i tipi di evento sconosciuti in un ramo default per evitare che nuovi tipi interrompano l'endpoint. Vedi Verificare le firme dei webhook per il contratto completo.
Gli eventi presence contano i membri
member_added e member_removed seguono l'identità, quindi non corrispondono uno-a-uno con le connessioni. Una persona con la tua app aperta in tre schede è un solo membro:
| Cosa succede | Webhook |
|---|---|
| La prima scheda si iscrive | realtime.member_added |
| La seconda scheda si iscrive | nessuno |
| La seconda scheda si chiude | nessuno |
| L'ultima scheda si chiude | realtime.member_removed |
Usa member_removed per rilevare quando un'identità lascia un canale. La chiusura di una singola sessione non lo attiva finché un'altra sessione rimane attiva. Per tracciare le connessioni, iscriviti a realtime.connection_count. Vedi Canali presence.
Comportamento di consegna dei webhook Realtime
Le consegne Realtime usano queste regole di ripetizione e visibilità:
- Restituisci 2xx tempestivamente dopo aver accettato l'evento in modo durevole, poi elaboralo in modo asincrono.
- Se l'endpoint restituisce una risposta diversa da 2xx, Realtime riprova con backoff esponenziale per un massimo di 5 minuti.
- Gli eventi Realtime non prevedono replay e non compaiono nel log dei tentativi di consegna dell'endpoint.
- Mettere in pausa l'endpoint interrompe le consegne Realtime insieme a tutto il resto; riattivarlo le riprende.
Le consegne non sono ordinate e non forniscono una ricevuta per evento. Trattale come notifiche di cambiamento. Usa Interrogare lo stato del canale per recuperare lo stato corrente dopo eventi ritardati o mancanti.
Passi successivi
- Eventi client è il gruppo i cui nomi di evento e payload definisci tu.
- Canali cache spiega cosa fare con realtime.cache_miss.
- Webhook ed eventi copre la configurazione degli endpoint, la verifica delle firme e la rotazione dei secret per ogni webhook Bird.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Esplora la funzionalitàRealtimeSegui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first realtime event
Prova l'esercitazione e ottieni un brief di implementazione