वेबहुक — आपके सिस्टम में वास्तविक-समय मॉडरेशन घटनाएँ

1वेबहुक क्या करते हैं

API को पोल करने के बजाय, आप एक URL रजिस्टर करते हैं और जब भी आपके समूह में कुछ होता है Telm उस पर एक हस्ताक्षरित HTTP POST भेजता है। इसी तरह आप मॉडरेशन घटनाओं को अपने ख़ुद के सिस्टम में — एक डैशबोर्ड, एक डेटा वेयरहाउस, एक अलर्टिंग चैनल — वास्तविक समय में पाते हैं।

आप वेबहुक एंडपॉइंट को API के ज़रिए प्रबंधित करते हैं: एक URL रजिस्टर करें, चुनें कि किन घटनाओं की सदस्यता लेनी है, वैकल्पिक रूप से उन्हें विशिष्ट समूहों तक सीमित करें, एक टेस्ट पिंग भेजें, और हाल का डिलीवरी लॉग पढ़ें।

2पुश पोलिंग से क्यों बेहतर है

नई घटनाएँ खोजने के लिए आप जर्नल एंडपॉइंट को एक टाइमर पर कॉल कर सकते हैं, लेकिन यह लेटेंसी जोड़ता है, कोटा ख़र्च करता है, और उस ठीक क्षण को चूक सकता है जब कुछ होता है। वेबहुक मॉडल को पलट देते हैं: Telm आपको उसी क्षण बताता है जब कोई घटना फ़ायर होती है, इसलिए आपके सिस्टम सेकंड में प्रतिक्रिया देते हैं।

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

• वास्तविक-समय: आप किसी घटना के बारे में तब जानते हैं जब वह होती है, आपके अगले पोल पर नहीं।
• कुशल: कोई दोहराई गई पढ़ाई नहीं जो आपके दैनिक कोटा में खाती है।
• पूर्ण: डिलीवरी फिर से कोशिश की जाती हैं, इसलिए आपकी ओर का एक संक्षिप्त आउटेज घटनाएँ नहीं खोता।

3वे घटनाएँ जिनकी आप सदस्यता ले सकते हैं

सात सदस्यता-योग्य घटना प्रकार हैं, जो स्पैम निर्णयों, दंडों और सदस्यता परिवर्तनों को कवर करते हैं। एक अकेला मॉडरेट किया गया संदेश एक से अधिक घटना पैदा कर सकता है — एक स्पैम संदेश जो एक बैन में समाप्त होता है spam.detected और user.banned दोनों उत्सर्जित करता है।

• spam.detected — इंजन ने एक संदेश को स्पैम के रूप में फ़्लैग किया।
• message.suspicious — एक स्कोर के साथ एक शैडो (मॉनिटरिंग-मोड) डिटेक्शन।
• user.banned — एक सदस्य को बैन किया गया।
• user.kicked — एक सदस्य को हटाया गया।
• user.muted — एक सदस्य को म्यूट किया गया।
• user.joined — एक सदस्य समूह में जॉइन हुआ।
• user.left — एक सदस्य समूह से चला गया।

4पेलोड लिफ़ाफ़ा

हर डिलीवरी शीर्ष-स्तरीय फ़ील्ड के एक छोटे, स्थिर सेट और अंदर एक घटना-विशिष्ट data ऑब्जेक्ट के साथ एक JSON लिफ़ाफ़ा है। आप विवरण को तब तक पार्स किए बिना type और समय पर रूट कर सकते हैं जब तक आपको उनकी ज़रूरत न हो।

• id — एक अद्वितीय डिलीवरी id; उसी घटना की पुनर्डिलीवरी वही id फिर से उपयोग करती है, इसी तरह आप डिडुप्लिकेट करते हैं।
• type — घटना प्रकार, ऊपर के सात में से एक।
• created_at — जब घटना फ़ायर हुई, RFC3339 UTC में।
• group_id — वह समूह जिससे घटना संबंधित है (जब लागू हो)।
• data — एक घटना-विशिष्ट ऑब्जेक्ट: स्पैम घटनाओं के लिए संदेश और निर्णय विवरण, सदस्यता घटनाओं के लिए सदस्य विवरण।

5यह सत्यापित करना कि डिलीवरी सचमुच Telm से हैं

हर डिलीवरी हस्ताक्षरित होती है ताकि आपका सर्वर पुष्टि कर सके कि अनुरोध सचमुच Telm से आया और पारगमन में उससे छेड़छाड़ नहीं हुई। पेलोड पर भरोसा करने से पहले हस्ताक्षर मान्य करें, और जो कुछ भी मेल नहीं खाता उसे अस्वीकार करें।

हस्ताक्षर टाइमस्टैम्प और कच्ची अनुरोध बॉडी का एक HMAC-SHA256 है, जो आपके एंडपॉइंट हस्ताक्षर रहस्य से कीड किया गया है। सत्यापित करने के लिए, टाइमस्टैम्प हेडर और आपको प्राप्त ठीक बाइट्स पर HMAC फिर से गणना करें, और इसकी तुलना हस्ताक्षर हेडर से करें।

• X-Telm-Signature — हस्ताक्षर, v1 के रूप में स्वरूपित जिसके बाद टाइमस्टैम्प के बॉडी से जुड़ने का हेक्स HMAC-SHA256 होता है।
• X-Telm-Timestamp — यूनिक्स-सेकंड टाइमस्टैम्प जो हस्ताक्षरित है, ताकि आप बासी या रीप्ले की गई डिलीवरी अस्वीकार कर सकें।
• X-Telm-Event — घटना प्रकार, और X-Telm-Delivery — डिडुप्लिकेशन के लिए डिलीवरी id।
• हस्ताक्षर रहस्य एक बार दिखाया जाता है जब आप एंडपॉइंट बनाते हैं और whsec_ से शुरू होता है। इसे सुरक्षित रूप से संग्रहित करें; यही एकमात्र चीज़ है जो साबित करती है कि एक डिलीवरी असली है।

6विश्वसनीय, डिडुप्लिकेट की गई डिलीवरी

डिलीवरी कम-से-कम-एक-बार है: Telm सुनिश्चित करता है कि एक घटना आप तक पहुँचे, जिसका मतलब है कि वही घटना कभी-कभार दो बार आ सकती है। चूँकि हर पुनर्डिलीवरी वही डिलीवरी id फिर से उपयोग करती है, आप उन id को संग्रहित करके डिडुप्लिकेट करते हैं जिन्हें आपने प्रोसेस किया और दोहराव छोड़ते हैं।

अगर आपका एंडपॉइंट पहुँच से बाहर है या कोई त्रुटि लौटाता है, तो डिलीवरी एक निश्चित शेड्यूल पर फिर से कोशिश की जाती है — मोटे तौर पर एक मिनट, पाँच मिनट, तीस मिनट, दो घंटे और छह घंटे के बाद, लगभग साढ़े आठ घंटे में छह प्रयास तक। एक एंडपॉइंट जो विफल होता रहता है उसे दोनों पक्षों की रक्षा के लिए अपने आप निष्क्रिय कर दिया जाता है, और मालिक को सूचित किया जाता है।

• एक 2xx स्थिति के साथ जल्दी जवाब दें; स्वीकार करने के बाद भारी काम अतुल्यकालिक रूप से करें।
• डिलीवरी id पर डिडुप्लिकेट करें — कभी पेलोड सामग्री पर नहीं।
• एक एंडपॉइंट जो 72-घंटे की विंडो के भीतर बिना किसी सफलता के लगातार लगभग बीस बार विफल होता है वह अपने आप निष्क्रिय हो जाता है; अपने सर्वर के स्वस्थ होने पर इसे फिर से सक्षम करें।

7एंडपॉइंट प्रबंधित करना और लॉग पढ़ना

आप वेबहुक एंडपॉइंट को API के ज़रिए रजिस्टर, संपादित और हटाते हैं। जब आप एक बनाते हैं तो आपको हस्ताक्षर रहस्य ठीक एक बार मिलता है, सदस्यता लेने के लिए घटनाएँ चुनते हैं, और वैकल्पिक रूप से इसे विशिष्ट समूहों तक सीमित करते हैं। एक टेस्ट कॉल एक हस्ताक्षरित पिंग भेजता है ताकि आप असली ट्रैफ़िक शुरू होने से पहले पुष्टि कर सकें कि आपका सत्यापन काम करता है।

हर एंडपॉइंट एक डिलीवरी लॉग रखता है जिसे आप यह देखने के लिए वापस पढ़ सकते हैं कि क्या भेजा गया, कब, और क्या यह सफल रहा — अगली लाइव घटना का इंतज़ार किए बिना एक रिसीवर को डिबग करने के लिए सुविधाजनक।

• एक एंडपॉइंट बनाएँ और whsec_ रहस्य तुरंत कॉपी करें।
• अपने हस्ताक्षर जाँच को शुरू से अंत तक मान्य करने के लिए एक टेस्ट पिंग भेजें।
• एक एंडपॉइंट को एक समूह तक सीमित करें या इसे उन सभी समूहों के लिए खुला छोड़ें जिनका आप प्रशासन करते हैं।
• हाल के प्रयासों और उनके परिणामों की जाँच के लिए डिलीवरी लॉग पढ़ें।

8सर्वोत्तम अभ्यास और आम ग़लतियाँ

एक मज़बूत रिसीवर कुछ नियमों का अनुसरण करता है जो सबसे आम समस्याओं को रोकते हैं।

• कच्ची बॉडी बाइट्स पर हस्ताक्षर सत्यापित करें — पहले JSON में पार्स करना और फिर से क्रमबद्ध करना बाइट्स बदल सकता है और जाँच तोड़ सकता है।
• 2xx जल्दी लौटाएँ और बाद में प्रोसेस करें; एक धीमा हैंडलर टाइमआउट और बेकार की पुनः-कोशिशों का कारण बनता है।
• संचालन को इडेम्पोटेंट बनाएँ ताकि एक पुनर्डिलीवर की गई घटना दुगुनी न गिने।
• एक सार्वजनिक रूप से पहुँच योग्य URL पर HTTPS का उपयोग करें; Telm आंतरिक और निजी पतों को ब्लॉक करता है और रीडायरेक्ट का अनुसरण नहीं करता।
• whsec_ रहस्य को लॉग और क्लाइंट कोड से बाहर रखें।