वेबहुक

RolChat आपके सिस्टम तक इवेंट हस्ताक्षरित HTTP POST अनुरोधों के रूप में पहुँचाता है। यह पेज प्लगइन वेबहुक का वर्णन करता है; ऑटोमेशन नियम से भेजे गए वेबहुक दोबारा कोशिश, प्रतीक्षा समय और सीक्रेट रोटेशन में अलग हैं, देखें ऑटोमेशन वेबहुक। दूसरी दिशा में भी यही नियम लागू होते हैं, जब आपका सिस्टम, कोई प्लगइन या प्रदाता RolChat में पोस्ट करता है। किसी भी डिलीवरी पर कार्रवाई करने से पहले उसे नीचे दिए क्रम में सत्यापित करें।

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

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…

{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }

हेडर	अर्थ
X-RolChat-Timestamp	भेजने के समय Unix सेकंड। हस्ताक्षरित संदेश का हिस्सा।
X-RolChat-Signature	sha256=<hex>। प्रीफ़िक्स एल्गोरिदम का नाम बताता है ताकि बाद में उसे बदला जा सके।
X-RolChat-Nonce	इस HTTP अनुरोध के लिए यूनिक ULID। दोबारा कोशिश पर नया nonce मिलता है।
X-RolChat-Event-Id	इवेंट की अपनी ID। दोबारा कोशिशों में स्थिर; डुप्लिकेट हटाने के लिए इसका उपयोग करें।

आउटबाउंड डिलीवरी केवल HTTPS एंडपॉइंट पर जाती हैं। सदस्यता बनाते समय HTTP URL अस्वीकार हो जाता है।

हस्ताक्षर

हस्ताक्षरित संदेश टाइमस्टैम्प, एक शाब्दिक बिंदु, और अनुरोध का कच्चा बॉडी, बाइट दर बाइट है:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

जो बाइट आपको मिले उन पर हस्ताक्षर जाँचें, पार्स किए गए JSON की दोबारा सीरियलाइज़ की गई कॉपी पर नहीं। व्हाइटस्पेस या कुंजियों के क्रम में बदलाव हस्ताक्षर तोड़ देता है। SHA-256 ही एकमात्र स्वीकृत एल्गोरिदम है।

“HTTP अनुरोध भेजें” ऑटोमेशन कार्रवाई

Automation मॉड्यूल की HTTP कार्रवाई से भेजे गए अनुरोध दो हेडर से हस्ताक्षरित होते हैं। X-RolChat-Signature है sha256= के बाद केवल बॉडी का HMAC-SHA256। X-RolChat-Signature-V2 है <timestamp>.<body> का HMAC-SHA256, यानी ऊपर बताई गई योजना, जिसमें टाइमस्टैम्प के रूप में X-RolChat-Timestamp है। V2 हेडर सत्यापित करें; केवल बॉडी वाला हेडर दोहराए गए अनुरोध से सुरक्षा नहीं देता। इन अनुरोधों में X-RolChat-Nonce और X-RolChat-Event-Id नहीं होते; एक डिलीवरी की हर कोशिश में वही X-RolChat-Delivery-Id होता है और X-RolChat-Attempt में उसका अपना क्रमांक, इसलिए nonce जाँच छोड़ दें और X-RolChat-Delivery-Id से डुप्लिकेट हटाएँ। सत्यापन के नमूने X-RolChat-Signature पढ़ते हैं: ऑटोमेशन अनुरोधों के लिए इसके बजाय X-RolChat-Signature-V2 पढ़ें।

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

ये पाँच जाँचें क्रम से करें। Python, Node.js, Go, Ruby और PHP में उदाहरण सत्यापन उदाहरण पेज पर हैं।

1. ताज़गी। अगर |now − X-RolChat-Timestamp| > 300 सेकंड है तो अस्वीकार करें (400)। पाँच मिनट घड़ी के अंतर को सहन करते हैं और उसके बाद पकड़े गए अनुरोध को बेकार बना देते हैं। अपने सर्वर को NTP पर रखें।
2. हस्ताक्षर। अपेक्षित मान गणना करें और स्थिर-समय तुलना (hmac.compare_digest, crypto.timingSafeEqual, hash_equals) से मिलाएँ। मेल न खाने पर 401 से अस्वीकार करें। सामान्य स्ट्रिंग तुलना समय की जानकारी लीक करती है और स्वीकार्य नहीं है।
3. Nonce। X-RolChat-Nonce को 10 मिनट के TTL के साथ परमाणु set-if-absent (SET NX EX 600) से संग्रहीत करें। अगर यह पहले से मौजूद है, तो 409 से अस्वीकार करें: अनुरोध रीप्ले है। अगर आपका nonce स्टोर बंद है, तो 503 के साथ बंद रूप में विफल हों ताकि RolChat दोबारा कोशिश करे; कभी भी “स्वीकार” पर न जाएँ।
4. बॉडी को अब ही पार्स करें।
5. इवेंट ID से डुप्लिकेट हटाएँ। दोबारा कोशिशों में नया nonce होता है लेकिन वही X-RolChat-Event-Id। अगर आपने पिछले सात दिनों में वह ID प्रोसेस की है, तो दोबारा प्रोसेस किए बिना 200 लौटाएँ।

डिलीवरी सुरक्षित रूप से स्वीकार होते ही 2xx लौटाएँ; काम एसिंक्रोनस रूप से करें। RolChat जवाब के लिए 15 सेकंड इंतज़ार करता है।

सीक्रेट

• वेबहुक सीक्रेट 64 रैंडम बाइट है, base64url में एन्कोड किया हुआ (लगभग 86 अक्षर)। यह सदस्यता या प्लगइन बनने पर जनरेट होता है और एक बार दिखाया जाता है।
• इसे अपने वॉल्ट या एनवायरनमेंट में संग्रहीत करें; RolChat केवल एन्क्रिप्टेड कॉपी रखता है।
• 90 दिन बाद रोटेशन की सलाह दी जाती है; उत्पाद रिमाइंडर दिखाता है लेकिन रोटेट न करने पर कभी सदस्यता बंद नहीं करता।
• रोटेशन में ओवरलैप विंडो होती है: POST /api/v1/plugins/{id}/webhook-secret/rotate के बाद पुराना और नया दोनों सीक्रेट सात दिनों तक सत्यापित होते हैं, नई डिलीवरी नए से हस्ताक्षरित होती हैं, और विंडो के बाद पुराना हटा दिया जाता है। रोटेट करते ही कुछ नहीं टूटता।
• अगर सीक्रेट लीक हो जाए, तो POST /api/v1/plugins/{id}/webhook-secret/revoke उसे तुरंत अमान्य करता है, नया जारी करता है, खाते के एडमिन को ईमेल करता है और ऑडिट प्रविष्टि लिखता है।

दोबारा कोशिशें और डेड लेटर

2xx के अलावा कोई भी जवाब या नेटवर्क विफलता दोबारा कोशिश निर्धारित करती है:

प्रयास	पिछले के बाद देरी
1	तुरंत
2	15 सेकंड
3	1 मिनट
4	5 मिनट
5	30 मिनट
6	2 घंटे
7	8 घंटे
8	24 घंटे

408, 429, 5xx और नेटवर्क त्रुटियों पर दोबारा कोशिश होती है। 400, 401, 403, 404 और 410 पर नहीं: डिलीवरी सीधे डेड-लेटर कतार में जाती है, क्योंकि अस्वीकार हस्ताक्षर या गायब एंडपॉइंट पर दोबारा कोशिश से कोई मदद नहीं मिल सकती। आठ विफल प्रयासों के बाद भी डिलीवरी डेड-लेटर में चली जाती है।

डेड लेटर 30 दिन तक रखे जाते हैं और सेटिंग्स → प्लगइन → {plugin} → वेबहुक लॉग → DLQ में दिखते हैं, जहाँ एडमिन किसी एक को फिर से चला सकता है (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay)।

सीमाएँ

• आउटबाउंड बॉडी: डिफ़ॉल्ट रूप से 1 MB (हर प्लगइन के लिए कॉन्फ़िगर करने योग्य)। RolChat में इनबाउंड बॉडी: 5 MB। इससे बड़ा 413 है।
• प्लगइन allowed_source_ips घोषित कर सकता है; RolChat सत्यापन से पहले वह अनुमति सूची लागू करता है।
• अतिरिक्त जाँच के तौर पर आप RolChat-Webhook/1.0 यूज़र एजेंट पर भरोसा कर सकते हैं। यह सुरक्षा नियंत्रण नहीं है।

RolChat में आने वाले वेबहुक

प्रदाता अपनी हस्ताक्षर योजनाओं (Twilio, Telnyx, Bandwidth, WhatsApp के लिए Meta, Stripe) के साथ /api/v1/webhooks/{category}/{adapter} पर RolChat में पोस्ट करते हैं। हर एडैप्टर अपने प्रदाता का हस्ताक्षर सत्यापित करता है, पेलोड को सामान्य करता है और RolChat हस्ताक्षर के साथ आंतरिक इवेंट बस पर फिर से प्रकाशित करता है। आपका अपना सिस्टम ऊपर बताए गए उन्हीं X-RolChat-* हेडर के साथ RolChat में पोस्ट कर सकता है, उस प्लगइन के सीक्रेट से हस्ताक्षरित जिसके पास एंडपॉइंट है।

ऑटोमेशन वेबहुक

ऑटोमेशन मॉड्यूल की HTTP अनुरोध भेजें कार्रवाई के डिलीवरी के अपने नियम हैं:

• हर खाते के लिए एक सीक्रेट। इसे ऑटोमेशन स्क्रीन पर देखें या रोटेट करें (मालिक और एडमिन)। रोटेशन तुरंत लागू होता है: कोई ओवरलैप विंडो नहीं है, पुराना सीक्रेट तुरंत सत्यापित होना बंद हो जाता है, इसलिए पहले अपना रिसीवर अपडेट करें या थोड़ा अंतराल स्वीकार करें।
• प्रतीक्षा समय: RolChat जवाब के लिए 10 सेकंड इंतज़ार करता है।
• दोबारा कोशिश: कुल मिलाकर अधिकतम 6 कोशिशें। दूसरी कोशिश से पहले का अंतराल 30 सेकंड है, फिर लगभग 2 मिनट, 8 मिनट, 32 मिनट और 2 घंटे 8 मिनट, हर बार 20 % तक बदलता हुआ। एक अंतराल कभी 6 घंटे से अधिक नहीं होता।
• क्या दोबारा आज़माया जाता है: नेटवर्क त्रुटियाँ, टाइमआउट, 5xx, 408, 425 और 429। अन्य 4xx जवाब, अवरुद्ध पता या बहुत बड़ी बॉडी दोबारा नहीं आज़माई जातीं: डिलीवरी सीधे डेड-लेटर कतार में जाती है, जैसा आखिरी विफल कोशिश के बाद होता है।
• हेडर: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt।

अपने रिसीवर का परीक्षण

POST /api/v1/webhooks/test-signature कॉल करने वाले प्लगइन के एंडपॉइंट पर एक कृत्रिम हस्ताक्षरित इवेंट भेजता है, ताकि असली ट्रैफ़िक आने से पहले आप अपना इम्प्लीमेंटेशन शुरू से अंत तक सत्यापित कर सकें।

आम गलतियाँ

• कच्चे बाइट के बजाय पार्स करके दोबारा एन्कोड किए गए JSON पर सत्यापन।
• हस्ताक्षर मिलाने के लिए == का उपयोग।
• इवेंट ID के बजाय nonce से डुप्लिकेट हटाना (हर दोबारा कोशिश का nonce नया होता है)।
• पाँच मिनट से ज़्यादा आगे-पीछे चलती घड़ी।
• जवाब देने से पहले धीमा काम करना, फिर 15 सेकंड पर टाइमआउट होना और वही इवेंट फिर से पाना।