Webhook in tempo reale

Il publishing esce. I webhook tornano indietro.

I client si iscrivono e si disconnettono senza mai raggiungere il tuo backend, il che significa che il tuo backend non sa se qualcuno è in ascolto. I webhook chiudono il cerchio: l'edge invia un evento firmato quando un canale si riempie o si svuota, quando un membro arriva o esce, e quando un canale cache non ha nulla da servire.

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

Smetti di pagare per un pubblico inesistente.

Questa è l'ottimizzazione più economica di Bird Realtime. Un evento channel-occupied è il segnale per avviare il lavoro costoso, la sottoscrizione ai dati di mercato, il loop di pubblicazione al secondo; channel-vacated è il segnale per fermarlo. Nessun evento viene generato per gli iscritti che arrivano e partono nel frattempo, quindi i due eventi marcano esattamente i confini della vita di un canale e nient'altro.

Cinque gruppi. Iscriviti a ciò che ti serve.

Ti iscrivi a un gruppo; il gruppo fornisce i singoli tipi di evento. Un endpoint può gestire gli eventi Realtime insieme al resto della piattaforma, quindi email.bounced e realtime.presence possono arrivare sulla stessa rotta con lo stesso signing secret.

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 e vacated: i due estremi della vita di un canale, e nulla nel mezzo.
realtime.presenceMember added e removed. Segue l'identità, quindi la seconda scheda di una persona non produce nulla.
realtime.connection_countQuante connessioni ha un canale. Richiede il conteggio delle connessioni abilitato sull'app.
realtime.cache_channelsUn cache miss, ovvero il segnale per leggere lo stato corrente e pubblicarlo.
realtime.client_eventsUna consegna per evento client, con lo stesso nome: client-typing arriva come realtime.client-typing.

Cosa costruiscono le persone con i webhook

Quattro pattern in cui il server deve sapere cosa stanno facendo i client.

01
Lavoro che gira solo mentre qualcuno guarda.
Avvia il feed upstream, il poller o il render job su channel occupied e fermalo su channel vacated. Una dashboard che nessuno ha aperto non costa nulla da mantenere attiva.
02
Una copia backend del roster.
Member added e removed mantengono la tua vista di chi è in una stanza, che è ciò di cui è realmente fatto un indicatore di disponibilità agente o un conteggio posti. Seguono le identità, quindi una persona che chiude una delle tre schede non produce nulla.
03
Riempire una cache fredda.
Un client che si iscrive a un canale cache senza nulla in cache genera un miss sul tuo endpoint. Leggi lo stato corrente, pubblicalo, e il client che ha causato il miss lo riceve, perché a quel punto è già iscritto.
04
Monitorare il traffico peer-to-peer.
Gli eventi client viaggiano tra i client senza la tua API. Iscriviti al gruppo client-events e il tuo server riceve una copia, con il canale, l'ID connessione e, sui canali presence, l'ID membro. Da sapere prima di iscriverti: un segnale ad alta frequenza come la posizione del cursore produce una consegna per evento.

Firmati come ogni altro webhook Bird.

Le consegne seguono lo standard Standard Webhooks, con gli header webhook-id, webhook-timestamp e webhook-signature che verifichi rispetto al signing secret dell'endpoint. L'SDK decodifica e verifica in una sola chiamata. Verifica il body grezzo anziché una copia rielaborata, poiché la ri-serializzazione del JSON può alterare i byte firmati, e mantieni un branch predefinito in modo che un nuovo tipo di evento non possa interrompere la rotta.

Le garanzie di consegna, spiegate chiaramente.

Tratta questi come notifiche di cambiamento, non come un registro. Una risposta non-2xx viene ritentata con backoff esponenziale per un massimo di cinque minuti, dopodiché l'evento è perso: gli eventi Realtime non hanno replay e non compaiono nel log dei tentativi di consegna dell'endpoint. Le consegne non sono ordinate e non hanno ricevuta per evento, quindi dopo una consegna ritardata o mancante, leggi lo stato corrente dall'API channel-state anziché ricostruirlo. Restituisci 2xx non appena hai accettato in modo durevole l'evento e svolgi il lavoro successivamente.

Configurati nella dashboard.

Le sottoscrizioni Realtime si configurano nella pagina Webhooks: crea o modifica un endpoint, scegli un'app Realtime e seleziona i gruppi. L'app non può essere cambiata in seguito, ma i gruppi sì. Questa è l'unica parte della superficie webhook della piattaforma che oggi è esclusivamente da dashboard, e una richiesta API pubblica che include un tipo di evento Realtime viene rifiutata anziché accettata silenziosamente.

Approfondisci nella documentazione.

Webhook Realtime elenca ogni tipo consegnato e i relativi campi dati. Eventi client copre il gruppo che definisci tu, canali cache spiega cosa fare con un miss, e webhook ed eventi è il contratto a livello di piattaforma per endpoint, firme e rotazione dei secret.