Realtime webhooks

Publishing बाहर जाती है। Webhooks वापस आते हैं।

क्लाइंट सब्सक्राइब और डिस्कनेक्ट होते हैं और आपके बैकएंड तक कभी नहीं पहुँचते, यानी आपके बैकएंड को पता ही नहीं कि कोई सुन रहा है। Webhooks इस लूप को बंद करते हैं: edge एक signed event पोस्ट करता है जब कोई चैनल भरता या खाली होता है, जब कोई सदस्य आता या जाता है, और जब किसी cache चैनल के पास सर्व करने को कुछ नहीं होता।

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

बिना दर्शकों के लिए भुगतान बंद करें।

यह Bird Realtime में सबसे सस्ता ऑप्टिमाइज़ेशन है। channel-occupied इवेंट महँगे काम शुरू करने का संकेत है — market-data सब्सक्रिप्शन, प्रति-सेकंड publish लूप; channel-vacated इसे रोकने का संकेत है। बीच में आने-जाने वाले सब्सक्राइबर्स के लिए कुछ भी फायर नहीं होता, इसलिए ये दो इवेंट किसी चैनल के जीवनकाल के ठीक दो किनारे दर्शाते हैं, और कुछ नहीं।

पाँच समूह। जो चाहिए उसे सब्सक्राइब करें।

आप किसी समूह को सब्सक्राइब करते हैं; वह समूह अलग-अलग event types डिलीवर करता है। एक एंडपॉइंट बाकी प्लेटफ़ॉर्म इवेंट्स के साथ Realtime इवेंट्स भी ले सकता है, इसलिए email.bounced और realtime.presence एक ही रूट पर एक ही 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 और vacated: किसी चैनल के जीवनकाल के दो किनारे, और बीच में कुछ नहीं।
realtime.presenceMember added और removed। पहचान का अनुसरण करता है, इसलिए किसी व्यक्ति का दूसरा टैब कुछ भी उत्पन्न नहीं करता।
realtime.connection_countएक चैनल पर कितने कनेक्शन हैं। ऐप पर connection counting सक्षम होना ज़रूरी है।
realtime.cache_channelsएक cache miss, जो आपके लिए वर्तमान स्थिति पढ़ने और प्रकाशित करने का संकेत है।
realtime.client_eventsप्रत्येक client event के लिए एक डिलीवरी, उसी नाम से: client-typing, realtime.client-typing के रूप में आता है।

लोग इनसे क्या बनाते हैं

चार पैटर्न जिनमें सर्वर को यह जानना ज़रूरी है कि क्लाइंट क्या कर रहे हैं।

01
काम जो सिर्फ़ तभी चलता है जब कोई देख रहा हो।
channel occupied पर upstream फ़ीड, पोलर, या रेंडर जॉब शुरू करें और channel vacated पर बंद करें। जो डैशबोर्ड कोई खोलकर नहीं बैठा, उसे लाइव रखने की कोई लागत नहीं।
02
रोस्टर की बैकएंड कॉपी।
Member added और removed आपको यह अपना व्यू बनाए रखने देते हैं कि कमरे में कौन है — एजेंट-उपलब्धता इंडिकेटर या सीट काउंट असल में इसी से बनता है। ये पहचान का अनुसरण करते हैं, इसलिए तीन में से एक टैब बंद करने पर कुछ भी उत्पन्न नहीं होता।
03
ठंडे cache को भरना।
जब कोई क्लाइंट बिना कैश वाले cache चैनल को सब्सक्राइब करता है, तो आपके एंडपॉइंट पर एक miss ट्रिगर होता है। वर्तमान स्थिति पढ़ें, प्रकाशित करें, और जिस क्लाइंट ने miss पैदा किया वह इसे प्राप्त कर लेता है, क्योंकि वह तब तक पहले से सब्सक्राइब हो चुका होता है।
04
पीयर-टू-पीयर ट्रैफ़िक पर नज़र।
Client events आपके API के बिना क्लाइंट्स के बीच चलते हैं। client-events समूह को सब्सक्राइब करें और आपके सर्वर को चैनल, connection id, और presence चैनलों पर member id के साथ एक कॉपी मिलती है। सब्सक्राइब करने से पहले जानने लायक: कर्सर पोज़ीशन जैसा high-frequency सिग्नल प्रति इवेंट एक डिलीवरी उत्पन्न करता है।

हर दूसरे Bird webhook की तरह signed।

डिलीवरी Standard Webhooks का अनुसरण करती हैं, webhook-id, webhook-timestamp, और webhook-signature हेडर्स के साथ जिन्हें आप एंडपॉइंट के signing secret से वेरिफ़ाई करते हैं। SDK एक कॉल में unwrap और verify कर देता है। रॉ बॉडी को वेरिफ़ाई करें, re-parsed कॉपी को नहीं, क्योंकि JSON को दोबारा serialize करने से signed bytes बदल सकते हैं, और एक default branch रखें ताकि कोई नया event type रूट को तोड़ न सके।

डिलीवरी गारंटी, सीधे शब्दों में।

इन्हें लेजर नहीं, बल्कि change notifications मानें। non-2xx रिस्पॉन्स को exponential backoff के साथ पाँच मिनट तक retry किया जाता है, उसके बाद इवेंट चला जाता है: Realtime इवेंट्स में कोई replay नहीं है और ये एंडपॉइंट के delivery-attempts लॉग में नहीं दिखते। डिलीवरी अनऑर्डर्ड होती हैं और प्रति-इवेंट कोई रसीद नहीं होती, इसलिए देरी या गायब डिलीवरी के बाद, channel-state API से वर्तमान स्थिति पढ़ें, पुनर्निर्माण न करें। जैसे ही आपने इवेंट को स्थायी रूप से स्वीकार कर लिया, 2xx लौटाएँ और काम बाद में करें।

डैशबोर्ड में कॉन्फ़िगर किया गया।

Realtime सब्सक्रिप्शन Webhooks पेज पर सेट किए जाते हैं: एक एंडपॉइंट बनाएँ या एडिट करें, एक Realtime ऐप चुनें, और समूह चुनें। ऐप बाद में बदला नहीं जा सकता, लेकिन समूह बदले जा सकते हैं। प्लेटफ़ॉर्म के webhook सरफ़ेस का यह एकमात्र हिस्सा है जो अभी सिर्फ़ डैशबोर्ड से उपलब्ध है, और एक public API रिक्वेस्ट जिसमें realtime event type शामिल हो, चुपचाप स्वीकार होने के बजाय रिजेक्ट कर दी जाती है।

डॉक्स में गहराई से जानें।

Realtime webhooks हर डिलीवर किए गए type और उसके data fields की सूची देता है। Client events उस समूह को कवर करता है जिसे आप खुद नाम देते हैं, cache channels बताता है कि miss होने पर क्या करें, और webhooks and events एंडपॉइंट्स, signatures, और secret rotation के लिए प्लेटफ़ॉर्म-व्यापी अनुबंध है।