Realtime webhooks

Publishing इवेंट्स क्लाइंट्स तक भेजता है। Webhooks उल्टी दिशा में काम करते हैं: जब किसी चैनल पर कुछ होता है तो Realtime edge एक signed इवेंट आपके endpoint पर POST करता है।

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

पाँच इवेंट ग्रुप

एक या अधिक इवेंट ग्रुप सब्सक्राइब करें:

ग्रुप	यह किस सवाल का जवाब देता है	यह क्या डिलीवर करता है
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	क्लाइंट्स क्या भेज रहे हैं?	प्रति client event एक इवेंट, उसी के नाम से

channel_existence किसी चैनल के जीवनचक्र के केवल दो छोरों की रिपोर्ट करता है: channel_occupied जब कनेक्शन शून्य से एक होता है, channel_vacated जब आखिरी कनेक्शन जाता है। बीच में आने-जाने वाले subscribers कुछ नहीं भेजते, जिससे यह जानने का सस्ता तरीका है कि publishing करना सार्थक है या नहीं।

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

Endpoint सब्सक्राइब करें

Webhooks खोलें, कोई endpoint बनाएँ या एडिट करें, और Realtime events सेक्शन खोजें। एक Realtime ऐप और प्राप्त करने वाले ग्रुप चुनें।

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

Platform और Realtime इवेंट्स एक ही endpoint शेयर कर सकते हैं। उदाहरण के लिए, एक endpoint email.bounced और realtime.presence दोनों सब्सक्राइब कर सकता है। दोनों endpoint के signing secret का उपयोग करते हैं।

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

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

हर POST में Bird के स्टैंडर्ड webhook envelope में एक इवेंट होता है:

कोड उदाहरण

{
  "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_name, event, data, connection_id, साथ ही presence चैनल पर member_id

Client events के लिए, क्लाइंट event suffix चुनता है। client-typing ट्रिगर करने पर realtime.client-typing बनता है, और data.event में client-typing होता है। देखें Client events।

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

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

कोड उदाहरण

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

रॉ request body को सत्यापित करें क्योंकि JSON को parse और re-serialize करने से signed bytes बदल सकते हैं। अज्ञात event types को default ब्रांच में हैंडल करें ताकि नए types endpoint को न तोड़ें। पूरे contract के लिए Webhook signatures सत्यापित करें देखें।

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

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

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

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

Realtime webhook डिलीवरी व्यवहार

Realtime डिलीवरी इन फिर से प्रयास करने और visibility नियमों का पालन करती हैं:

इवेंट को स्थायी रूप से स्वीकार करने के बाद तुरंत 2xx लौटाएँ, फिर इसे asynchronously प्रोसेस करें।
अगर आपका endpoint non-2xx रिस्पॉन्स देता है, तो Realtime अधिकतम 5 मिनट तक exponential backoff के साथ फिर से प्रयास करता है।
Realtime इवेंट्स का कोई replay नहीं होता और ये endpoint के delivery-attempts लॉग में दिखाई नहीं देते।
Endpoint को pause करने से Realtime डिलीवरी बाकी सबके साथ बंद हो जाती है, और फिर से enable करने पर शुरू हो जाती है।

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

अगले कदम

Client events वह ग्रुप है जिसके event names और पेलोड आप खुद तय करते हैं।
Cache channels बताता है कि realtime.cache_miss के साथ क्या करना है।
Webhooks & events हर Bird webhook के लिए endpoint सेटअप, signature verification, और secret rotation को कवर करता है।

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