Telm मॉडरेशन events को आपके server पर रियल टाइम में धकेल सकता है। आप एक endpoint पंजीकृत करते हैं, चुनते हैं कि कौन से events पाने हैं, और Telm हर एक के लिए एक हस्ताक्षरित POST भेजता है। हर delivery एक HMAC-SHA256 हस्ताक्षर ले जाती है जिसे आप अपने endpoint secret से सत्यापित करते हैं। विफल deliveries एक अनुसूची पर पुनः प्रयास की जाती हैं; एक स्थायी रूप से अगम्य endpoint अपने-आप निष्क्रिय हो जाता है।
1Event envelope
हर webhook एक HTTP POST है जिसका JSON body एक साझा envelope में होता है। envelope में एक id (डी-डुप्लीकेशन के लिए एक अद्वितीय delivery पहचानकर्ता), एक type (event नाम), एक created_at टाइमस्टैम्प, वह group_id जिससे event संबंधित है, और एक data ऑब्जेक्ट होता है जिसका आकार event type पर निर्भर करता है।
id असली events के लिए नियतात्मक है, इसलिए यदि वही event दो बार delivered हो — उदाहरण के लिए किसी पुनर्प्रयास के बाद — तो आपको दोनों बार वही id मिलता है। X-Telm-Delivery header (जो इस id को दर्पण करता है) को एक idempotency कुंजी के रूप में उपयोग करें ताकि आपका handler हर event को केवल एक बार संसाधित करे।
- Envelope फ़ील्ड: id, type, created_at, group_id, data।
- type नीचे दिए catalog से किसी एक event नाम में से है।
- data event-विशिष्ट फ़ील्ड ले जाता है।
- पुनर्प्रयासों को डी-डुप्लीकेट करने के लिए id (और X-Telm-Delivery header) उपयोग करें।
2Event catalog
आप किसी endpoint को catalog के किसी भी उपसमुच्चय पर subscribe करते हैं। spam.detected तब चलता है जब इंजन किसी संदेश को स्पैम फ़्लैग करता है। message.suspicious monitoring mode में चलता है, जब इंजन ने कार्रवाई की होती पर संदेश को केवल shadow-स्कोर किया। member events लोगों के प्रवेश, प्रस्थान, और दंडित होने को ढँकते हैं।
ping event विशेष है: यह subscribe-योग्य catalog का हिस्सा नहीं है और केवल तब भेजा जाता है जब आप किसी endpoint के लिए एक परीक्षण delivery ट्रिगर करते हैं, ताकि आप अपने रिसीवर और हस्ताक्षर जाँच के छोर-से-छोर काम करने की पुष्टि कर सकें।
- spam.detected — कोई संदेश स्पैम के रूप में वर्गीकृत हुआ।
- message.suspicious — एक shadow (monitoring-mode) पहचान।
- user.banned, user.kicked, user.muted — एक मॉडरेशन क्रिया लागू हुई।
- user.joined, user.left — कोई सदस्य ग्रुप में आया या छोड़ गया।
- ping — एक मैनुअल परीक्षण event, कभी असली गतिविधि से नहीं चलता।
3प्रति event payload फ़ील्ड
spam.detected और message.suspicious के लिए, data ऑब्जेक्ट message_id, user_id, username, संदेश टेक्स्ट (बहुत लंबे संदेशों के लिए छाँटा हुआ), ली गई action, एक category, एक reason, पहचानी गई language, और एक confidence स्कोर ले जाता है। message.suspicious अतिरिक्त रूप से shadow score ले जाता है।
member events (user.joined, user.left, user.banned, user.kicked, user.muted) के लिए, data ऑब्जेक्ट user_id, username, first_name, एक वैकल्पिक message_id, और जहाँ लागू हो वहाँ एक reason ले जाता है। एक अंतर्निहित event एक से अधिक webhook उत्पन्न कर सकता है — एक स्पैम संदेश जो किसी बैन को ट्रिगर करता है spam.detected और user.banned दोनों के रूप में delivered होता है।
- Spam events: message_id, user_id, username, text, action, category, reason, language, confidence (और message.suspicious के लिए score)।
- Member events: user_id, username, first_name, message_id, reason।
- एक अकेली घटना कई events उत्सर्जित कर सकती है; उन्हें user_id और group_id से सहसंबंधित करें।
4HMAC हस्ताक्षर सत्यापित करना
हर delivery हस्ताक्षरित होती है ताकि आप निश्चित हो सकें कि यह सचमुच Telm से आई और उससे छेड़छाड़ नहीं हुई। आपको एक endpoint secret मिलता है (यह whsec_ से शुरू होता है) एक बार, जब आप endpoint बनाते हैं। इसे संग्रहित करें और हर आने वाले अनुरोध को सत्यापित करने के लिए उपयोग करें।
सत्यापित करने के लिए, X-Telm-Timestamp header मान लें, एक डॉट जोड़ें, फिर ठीक कच्चा अनुरोध body जोड़ें, और उस स्ट्रिंग का HMAC-SHA256 अपने endpoint secret को कुंजी के रूप में उपयोग करके गणना करें। परिणाम को hex-एन्कोड करें और उसे v1= से उपसर्ग करें — यह X-Telm-Signature header के बराबर होना चाहिए। एक स्थिर-समय तुलना से तुलना करें, और अनुरोध अस्वीकार करें यदि टाइमस्टैम्प कुछ मिनट से पुराना हो (पाँच एक अच्छा कट-ऑफ़ है) ताकि replays रोके जा सकें।
- X-Telm-Event — event type।
- X-Telm-Delivery — delivery id (idempotency कुंजी)।
- X-Telm-Timestamp — unix सेकंड, replays रोकने के लिए हस्ताक्षरित।
- X-Telm-Signature — v1= और टाइमस्टैम्प, एक डॉट, और कच्चे body का hex HMAC-SHA256।
5Delivery, पुनर्प्रयास और auto-disable
कोई delivery केवल तभी सफल गिनी जाती है जब आपका endpoint 2xx स्थिति के साथ प्रतिक्रिया दे। कुछ और — कोई गैर-2xx कोड, एक timeout, या एक कनेक्शन त्रुटि — विफलता मानी जाती है और एक निश्चित अनुसूची पर पुनः प्रयास की जाती है: तुरंत, फिर 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे और 6 घंटे बाद, छह प्रयासों के लिए जो delivery के विफल के रूप में बंद होने से पहले मोटे तौर पर साढ़े आठ घंटे तक फैले हैं।
यदि कोई endpoint विफल होता रहे — तीन दिन तक बिना किसी सफल delivery के कम से कम बीस लगातार विफलताएँ — तो Telm इसे अपने-आप निष्क्रिय कर देता है ताकि यह किसी मृत URL पर भेजना बंद कर दे। आप अपने रिसीवर के फिर स्वस्थ होने पर इसे डैशबोर्ड से फिर सक्रिय कर सकते हैं।
- सफलता = HTTP 2xx। तेज़ी से प्रतिक्रिया दें (लगभग दस सेकंड के भीतर) और भारी काम अतुल्यकालिक रूप से करें।
- पुनर्प्रयास अनुसूची: तुरंत, +1m, +5m, +30m, +2h, +6h (छह प्रयास)।
- 72 घंटे में बिना किसी सफलता के 20 लगातार विफलताओं के बाद auto-disabled।
- Webhooks पंजीकृत करने को Pro प्लान या उच्चतर चाहिए।