Webhook realtime

Publishing keluar. Webhook kembali masuk.

Klien berlangganan dan terputus tanpa pernah menjangkau backend Anda, yang berarti backend Anda tidak tahu ada yang mendengarkan. Webhook menutup celah itu: edge mengirimkan event bertanda tangan saat channel terisi atau kosong, saat anggota bergabung atau keluar, dan saat cache channel tidak memiliki apa pun untuk disajikan.

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

Berhenti membayar untuk audiens yang tidak ada.

Ini adalah optimasi termurah di Bird Realtime. Event channel-occupied adalah sinyal untuk memulai pekerjaan berat, langganan data pasar, loop publish per detik; channel-vacated adalah sinyal untuk menghentikannya. Tidak ada yang terpicu untuk subscriber yang datang dan pergi di antaranya, jadi kedua event tersebut menandai tepat di ujung siklus hidup channel dan tidak lebih.

Lima grup. Langgani sesuai kebutuhan Anda.

Anda berlangganan ke sebuah grup; grup tersebut mengirimkan tipe event individual. Satu endpoint dapat membawa event Realtime bersama dengan event platform lainnya, jadi email.bounced dan realtime.presence bisa masuk di rute yang sama dengan signing secret yang sama.

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 dan vacated: dua ujung siklus hidup channel, dan tidak ada di antaranya.
realtime.presenceMember added dan removed. Mengikuti identitas, jadi tab kedua seseorang tidak menghasilkan apa pun.
realtime.connection_countBerapa banyak koneksi yang dimiliki sebuah channel. Memerlukan penghitungan koneksi yang diaktifkan pada aplikasi.
realtime.cache_channelsCache miss, yang merupakan isyarat bagi Anda untuk membaca state terkini dan mempublikasikannya.
realtime.client_eventsSatu pengiriman per event klien, dinamai sesuai event-nya: client-typing tiba sebagai realtime.client-typing.

Apa yang dibangun orang dengannya

Empat pola yang membutuhkan server untuk mengetahui apa yang dilakukan klien.

01
Pekerjaan yang hanya berjalan saat ditonton.
Mulai feed upstream, poller, atau render job saat channel occupied dan hentikan saat channel vacated. Dashboard yang tidak dibuka siapa pun tidak memerlukan biaya untuk tetap aktif.
02
Salinan backend dari daftar anggota.
Member added dan removed menjaga tampilan Anda sendiri tentang siapa yang ada di ruangan, yang merupakan dasar sebenarnya dari indikator ketersediaan agen atau penghitung kursi. Mereka mengikuti identitas, jadi seseorang yang menutup satu dari tiga tab tidak menghasilkan apa pun.
03
Mengisi cache yang kosong.
Klien yang berlangganan ke cache channel tanpa apa pun yang di-cache memicu miss pada endpoint Anda. Baca state terkini, publikasikan, dan klien yang menyebabkan miss tersebut menerimanya, karena sudah berlangganan saat itu.
04
Memantau lalu lintas peer-to-peer.
Event klien berpindah antar klien tanpa API Anda. Langgani grup client-events dan server Anda mendapat salinannya, lengkap dengan channel, connection id, dan pada presence channel juga member id. Perlu diketahui sebelum berlangganan: sinyal frekuensi tinggi seperti posisi kursor menghasilkan satu pengiriman per event.

Ditandatangani seperti setiap webhook Bird lainnya.

Pengiriman mengikuti Standard Webhooks, dengan header webhook-id, webhook-timestamp, dan webhook-signature yang Anda verifikasi terhadap signing secret endpoint. SDK membuka dan memverifikasi dalam satu panggilan. Verifikasi body mentah alih-alih salinan yang di-parse ulang, karena re-serialisasi JSON dapat mengubah byte yang ditandatangani, dan sediakan branch default agar tipe event baru tidak merusak rute.

Jaminan pengiriman, dinyatakan dengan jelas.

Perlakukan ini sebagai notifikasi perubahan, bukan buku besar. Respons non-2xx akan diulang dengan exponential backoff hingga lima menit, setelah itu event hilang: event Realtime tidak memiliki replay dan tidak muncul di log delivery-attempts endpoint. Pengiriman tidak berurutan dan tidak membawa tanda terima per event, jadi setelah pengiriman tertunda atau hilang, baca state terkini dari API channel-state alih-alih merekonstruksinya. Kembalikan 2xx segera setelah Anda menerima event secara durable dan lakukan pekerjaannya setelahnya.

Dikonfigurasi di dashboard.

Langganan Realtime diatur di halaman Webhooks: buat atau edit endpoint, pilih satu aplikasi Realtime, dan pilih grupnya. Aplikasi tidak dapat diubah setelahnya, meskipun grupnya bisa. Ini adalah satu-satunya bagian dari permukaan webhook platform yang saat ini hanya tersedia di dashboard, dan permintaan API publik yang menyertakan tipe event realtime akan ditolak alih-alih diterima secara diam-diam.

Pelajari lebih dalam di dokumentasi.

Webhook Realtime mencantumkan setiap tipe yang dikirim beserta field datanya. Event klien membahas grup yang Anda beri nama sendiri, cache channel menjelaskan apa yang harus dilakukan saat miss, dan webhook dan event adalah kontrak platform-wide untuk endpoint, tanda tangan, dan rotasi secret.