Realtime वेबहुक

पब्लिश करने पर इवेंट क्लाइंट तक भेजे जाते हैं। वेबहुक उलटी दिशा में काम करते हैं: जब किसी चैनल पर कुछ होता है, तो Realtime एज आपके एंडपॉइंट पर एक हस्ताक्षरित इवेंट POST करता है।

आप चैनल की स्थिति क्वेरी करना से ज़रूरत पड़ने पर चैनल की स्थिति पढ़ सकते हैं। वेबहुक से आपको पोलिंग के बिना किसी बदलाव की सूचना उसी समय मिलती है: कोई क्लाइंट सब्सक्राइब करता है, कोई सदस्य अपना आख़िरी टैब बंद करता है, या एक क्लाइंट दूसरे को कर्सर की स्थिति भेजता है।

पाँच इवेंट समूह

एक या अधिक इवेंट समूहों को सब्सक्राइब करें:

समूह	यह किस सवाल का जवाब देता है	यह क्या भेजता है
`realtime.channel_existence`	क्या कोई सुन रहा है?	`realtime.channel_occupied`, `realtime.channel_vacated`
`realtime.presence`	यहाँ कौन मौजूद है?	`realtime.member_added`, `realtime.member_removed`
`realtime.connection_count`	कितने कनेक्शन हैं?	`realtime.connection_count`
`realtime.cache_channels`	क्या इस चैनल को डेटा चाहिए?	`realtime.cache_miss`
`realtime.client_events`	क्लाइंट क्या भेज रहे हैं?	`realtime.client_event`

channel_existence किसी चैनल के जीवन के केवल दो छोरों की रिपोर्ट करता है: channel_occupied जब चैनल शून्य कनेक्शन से एक कनेक्शन पर पहुँचता है, और channel_vacated जब उसका आखिरी कनेक्शन चला जाता है। इनके बीच सब्सक्राइबर के आने और जाने से कोई इवेंट नहीं बनता। इसलिए यह जानने का यह सस्ता तरीका है कि पब्लिश करना फ़ायदेमंद है या नहीं।

connection_count के लिए ऐप पर कनेक्शन गिनती चालू होनी चाहिए। यदि यह सेटिंग बंद है, तो सब्सक्राइब किया गया समूह कोई इवेंट नहीं भेजता।

किसी एंडपॉइंट को सब्सक्राइब करें

Webhooks खोलें, कोई एंडपॉइंट बनाएँ या संपादित करें, और Realtime events सेक्शन ढूँढें। एक Realtime ऐप चुनें और वे समूह चुनें जिनके इवेंट आप पाना चाहते हैं।

प्लेटफ़ॉर्म इवेंट सब्सक्रिप्शन पूरे वर्कस्पेस पर लागू होते हैं, जबकि realtime.* सब्सक्रिप्शन एक ऐप के होते हैं। एंडपॉइंट बनाने के बाद आप उसका Realtime ऐप नहीं बदल सकते, लेकिन उसके सब्सक्राइब किए गए समूह अपडेट कर सकते हैं।

प्लेटफ़ॉर्म और Realtime इवेंट एक ही एंडपॉइंट साझा कर सकते हैं। उदाहरण के लिए, एक एंडपॉइंट email.bounced और realtime.presence दोनों को सब्सक्राइब कर सकता है। दोनों एंडपॉइंट के साइनिंग सीक्रेट का उपयोग करते हैं।

Realtime समूह केवल डैशबोर्ड से कॉन्फ़िगर होते हैं। जिस सार्वजनिक POST /v1/webhooks अनुरोध में realtime.* इवेंट टाइप शामिल हो, उसे अस्वीकार कर दिया जाता है, इसलिए ये सब्सक्रिप्शन डैशबोर्ड में कॉन्फ़िगर करें।

डिलीवरी कैसी दिखती है

हर POST में Bird के मानक वेबहुक एनवेलप में एक इवेंट होता है:

कोड उदाहरण

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

type डिलीवर किए गए इवेंट की पहचान बताता है। उदाहरण के लिए, realtime.presence समूह realtime.member_added और realtime.member_removed डिलीवर करता है:

डिलीवर किया गया `type`	`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`, `event`, `data`, `connection_id`, और presence चैनल पर `member_id` भी

क्लाइंट इवेंट के लिए type का मान realtime.client_event होता है, और data.event में मूल क्लाइंट इवेंट का नाम होता है, जैसे client-typing। data.channel चैनल की पहचान करता है, और data.data एक JSON स्ट्रिंग है जिसमें क्लाइंट का पेलोड होता है। क्लाइंट इवेंट देखें।

डिलीवरी का सत्यापन

Realtime webhooks Standard Webhooks का पालन करते हैं और इनमें webhook-id, webhook-timestamp और webhook-signature हेडर शामिल होते हैं। एंडपॉइंट के साइनिंग सीक्रेट से इनका सत्यापन करें।

कोड उदाहरण

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

कच्चे अनुरोध बॉडी का सत्यापन करें, क्योंकि JSON को पार्स करके दोबारा सीरियलाइज़ करने से साइन किए गए बाइट बदल सकते हैं। अज्ञात इवेंट प्रकारों को default ब्रांच में संभालें, ताकि नए प्रकार आने पर एंडपॉइंट न टूटे। पूरे अनुबंध के लिए webhook सिग्नेचर का सत्यापन करें देखें।

Presence इवेंट सदस्यों की गिनती करते हैं

member_added और member_removed पहचान (identity) के आधार पर चलते हैं, इसलिए ये कनेक्शन से एक-एक करके मेल नहीं खाते। जिस व्यक्ति ने आपका ऐप तीन टैब में खोला है, वह एक ही सदस्य है:

क्या होता है	Webhook
पहला टैब सब्सक्राइब करता है	`realtime.member_added`
दूसरा टैब सब्सक्राइब करता है	कोई नहीं
दूसरा टैब बंद होता है	कोई नहीं
आख़िरी टैब बंद होता है	`realtime.member_removed`

कोई पहचान किसी चैनल से कब निकलती है, यह पता करने के लिए member_removed का उपयोग करें। जब तक कोई दूसरा सेशन बचा है, एक सेशन के ख़त्म होने से यह ट्रिगर नहीं होता। कनेक्शन ट्रैक करने के लिए realtime.connection_count को सब्सक्राइब करें। प्रेज़ेंस चैनल देखें।

Realtime वेबहुक डिलीवरी का व्यवहार

Realtime डिलीवरी पर फिर से प्रयास करने और दृश्यता के ये नियम लागू होते हैं:

इवेंट को स्थायी रूप से स्वीकार करने के बाद तुरंत 2xx लौटाएँ, फिर उसे एसिंक्रोनस रूप से प्रोसेस करें।
अगर आपका एंडपॉइंट non-2xx प्रतिक्रिया लौटाता है, तो Realtime एक्सपोनेंशियल बैकऑफ़ के साथ अधिकतम 5 मिनट तक फिर से प्रयास करता है।
Realtime इवेंट को दोबारा चलाया नहीं जा सकता, और वे एंडपॉइंट के डिलीवरी-प्रयास लॉग में नहीं दिखते।
एंडपॉइंट को रोकने पर बाकी सभी डिलीवरी के साथ Realtime डिलीवरी भी रुक जाती हैं, और इसे फिर से सक्षम करने पर वे दोबारा शुरू हो जाती हैं।

डिलीवरी किसी तय क्रम में नहीं आतीं और हर इवेंट के लिए कोई रसीद नहीं मिलती। इन्हें बदलाव की सूचना मानें। देर से आए या छूटे हुए इवेंट के बाद मौजूदा स्थिति पाने के लिए चैनल स्थिति की क्वेरी करना का उपयोग करें।

अगले कदम

क्लाइंट इवेंट में realtime.client_event द्वारा लाए जाने वाले क्लाइंट इवेंट के नाम और पेलोड समझाए गए हैं।
कैश चैनल में बताया गया है कि realtime.cache_miss मिलने पर क्या करें।
वेबहुक और इवेंट में हर Bird वेबहुक के लिए एंडपॉइंट सेटअप, सिग्नेचर सत्यापन और सीक्रेट रोटेशन की जानकारी है।

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

अभ्यास करें और इम्प्लीमेंटेशन ब्रीफ़ पाएँ

संबंधित संसाधन