Webhook Realtime

Publishing mengirim event ke klien. Webhook bekerja sebaliknya: edge Realtime mengirim POST berupa event bertanda tangan ke endpoint Anda saat sesuatu terjadi di sebuah channel.

Anda sudah bisa membaca state channel sesuai kebutuhan dengan Querying channel state. Webhook adalah cara Anda mengetahui perubahan saat terjadi, tanpa polling: klien yang subscribe, anggota yang menutup tab terakhirnya, satu klien mengirim posisi kursor ke klien lain.

Lima grup event

Subscribe ke satu atau beberapa grup event:

Grup	Pertanyaan yang dijawab	Yang dikirimkan
realtime.channel_existence	Apakah ada yang mendengarkan?	realtime.channel_occupied, realtime.channel_vacated
realtime.presence	Siapa yang ada di sini?	realtime.member_added, realtime.member_removed
realtime.connection_count	Berapa jumlah koneksi?	realtime.connection_count
realtime.cache_channels	Apakah channel ini butuh data?	realtime.cache_miss
realtime.client_events	Apa yang dikirim klien?	satu event per client event, dinamai sesuai event tersebut

channel_existence hanya melaporkan dua titik ujung siklus hidup channel: channel_occupied saat channel berubah dari nol koneksi menjadi satu, channel_vacated saat koneksi terakhirnya pergi. Subscriber yang datang dan pergi di antaranya tidak menghasilkan apa pun, sehingga ini cara murah untuk mengetahui apakah publishing layak dilakukan.

connection_count memerlukan penghitungan koneksi pada app. Jika pengaturan ini dinonaktifkan, grup yang di-subscribe tidak menghasilkan event.

Buka Webhooks, buat atau edit endpoint, lalu temukan bagian Realtime events. Pilih satu app Realtime dan grup yang ingin diterima.

Subscription event platform berlaku di seluruh workspace, sedangkan subscription realtime.* milik satu app. Anda tidak bisa mengubah app Realtime endpoint setelah membuatnya, tetapi Anda bisa memperbarui grup yang di-subscribe.

Event platform dan Realtime bisa berbagi satu endpoint. Misalnya, satu endpoint bisa subscribe ke email.bounced dan realtime.presence. Keduanya menggunakan signing secret endpoint tersebut.

Grup Realtime saat ini hanya tersedia di dashboard. Request POST /v1/webhooks publik yang menyertakan tipe event realtime.* akan ditolak, jadi konfigurasikan subscription ini di dashboard.

Bentuk sebuah pengiriman

Setiap POST berisi satu event dalam envelope webhook standar Bird:

Contoh kode

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

type mengidentifikasi event yang dikirim. Misalnya, grup realtime.presence mengirimkan realtime.member_added dan realtime.member_removed:

type yang dikirim	Field 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, ditambah member_id pada presence channel

Untuk client event, klien memilih sufiks event. Memicu client-typing menghasilkan realtime.client-typing, dan data.event berisi client-typing. Lihat Client events.

Memverifikasi pengiriman

Webhook Realtime mengikuti Standard Webhooks dan menyertakan header webhook-id, webhook-timestamp, dan webhook-signature. Verifikasi dengan signing secret endpoint.

Contoh kode

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

Verifikasi body request mentah karena parsing dan serialisasi ulang JSON dapat mengubah byte yang ditandatangani. Tangani tipe event yang tidak dikenal dalam branch default agar tipe baru tidak merusak endpoint. Lihat Verifikasi tanda tangan webhook untuk kontrak lengkapnya.

Event presence menghitung anggota

member_added dan member_removed mengikuti identitas, sehingga tidak selalu satu-satu dengan koneksi. Seseorang yang membuka app Anda di tiga tab adalah satu anggota:

Yang terjadi	Webhook
Tab pertama subscribe	realtime.member_added
Tab kedua subscribe	tidak ada
Tab kedua ditutup	tidak ada
Tab terakhir ditutup	realtime.member_removed

Gunakan member_removed untuk mendeteksi kapan sebuah identitas meninggalkan channel. Satu sesi yang berakhir tidak memicunya selama sesi lain masih ada. Untuk melacak koneksi, subscribe ke realtime.connection_count. Lihat Presence channels.

Perilaku pengiriman webhook Realtime

Pengiriman Realtime menggunakan aturan coba lagi dan visibilitas berikut:

Kembalikan 2xx segera setelah menerima event secara durable, lalu proses secara asinkron.
Jika endpoint Anda mengembalikan respons non-2xx, Realtime mencoba lagi dengan exponential backoff hingga 5 menit.
Event Realtime tidak memiliki replay dan tidak muncul di log upaya pengiriman endpoint.
Menjeda endpoint menghentikan pengiriman Realtime bersama semua pengiriman lainnya, dan mengaktifkannya kembali melanjutkan pengiriman tersebut.

Pengiriman tidak berurutan dan tidak menyediakan tanda terima per event. Perlakukan sebagai notifikasi perubahan. Gunakan Querying channel state untuk mengambil state terkini setelah event yang tertunda atau hilang.

Langkah selanjutnya

Client events adalah grup yang nama event dan payload-nya Anda tentukan sendiri.
Cache channels menjelaskan apa yang harus dilakukan dengan realtime.cache_miss.
Webhooks & events membahas pengaturan endpoint, verifikasi tanda tangan, dan rotasi secret untuk setiap webhook Bird.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Jelajahi kemampuannyaRealtime Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first realtime event

Coba praktiknya dan dapatkan ringkasan implementasi