आउटगोइंग वेबहुक — डॉक्स

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

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

एक जोड़ें

अपने अकाउंट का सुरक्षा पेज खोलें (एडमिनिस्ट्रेटर: सुरक्षा; रीसेलर: लॉगिन सुरक्षा), और API टोकन के नीचे वेबहुक खोजें।

पता लिखें, उदाहरण के लिए https://example.com/hooks/panel।
जिन घटनाओं की आपको सूचना चाहिए उन पर निशान लगाएँ।
वेबहुक जोड़ें दबाएँ।

पैनल एक साइनिंग सीक्रेट (यह whsec_ से शुरू होता है) एक बार दिखाता है। उसे अभी कॉपी करें। वह एन्क्रिप्टेड रूप में सहेजा जाता है और दोबारा नहीं दिखाया जा सकता; अगर आप उसे खो दें, तो वेबहुक हटाकर नया जोड़ें।

हर व्यक्ति के अधिकतम 10 वेबहुक हो सकते हैं।

पता

यह https:// से शुरू होना चाहिए। सादा http:// अस्वीकार किया जाता है, क्योंकि कॉल में अकाउंट का विवरण होता है।
इसमें उपयोगकर्ता नाम या पासवर्ड नहीं होना चाहिए। इसके बजाय हस्ताक्षर जाँचें।
यह अधिकतम 500 अक्षरों का हो सकता है।
यह सार्वजनिक इंटरनेट पर होना चाहिए। इसी सर्वर के, निजी नेटवर्क के, लूपबैक इंटरफ़ेस के, या क्लाउड प्रदाता की मेटाडेटा रेंज के पते अस्वीकार किए जाते हैं — पता सहेजते समय भी और उस क्षण भी जब पैनल कनेक्ट करता है (इसलिए कोई होस्ट नाम जो बाद में निजी पते की ओर इशारा करे, वह भी काम नहीं करता)।
रीडायरेक्ट का पालन नहीं किया जाता। अंतिम पता दें।

घटनाएँ

घटना	कब भेजी जाती है
`account.created`	कोई होस्टिंग अकाउंट बनाया जाता है
`account.suspended`	कोई अकाउंट निलंबित किया जाता है
`account.unsuspended`	कोई निलंबित अकाउंट बहाल किया जाता है
`account.deleted`	कोई अकाउंट हटाया जाता है
`account.activity`	किसी अकाउंट पर अन्य गतिविधि

हर वेबहुक पर एक टेस्ट (परीक्षण कॉल) बटन ping नाम की घटना भेजता है, ताकि आप देख सकें कि आपका पता जवाब देता है। एक समय में केवल एक परीक्षण प्रतीक्षा में रह सकता है।

क्या भेजा जाता है

हर कॉल JSON बॉडी के साथ एक HTTP POST है:

{
  "event": "account.created",
  "at": "2026-10-23T08:15:00Z",
  "account": { "id": 42, "username": "example", "domain": "example.com" },
  "detail": "short text about what happened"
}

at UTC समय है। ping घटना का रूप {"event":"ping","at":"…","webhook_id":7} है।

ये हेडर हर कॉल के साथ आते हैं:

हेडर	अर्थ
`X-Nimbopanel-Event`	घटना का नाम, उदाहरण के लिए `account.created`
`X-Nimbopanel-Delivery`	एक संख्या जो इस डिलीवरी की पहचान करती है। उसी डिलीवरी का पुनः प्रयास वही संख्या रखता है, इसलिए डुप्लिकेट अनदेखा करने के लिए इसका उपयोग करें
`X-Nimbopanel-Timestamp`	कॉल पर हस्ताक्षर कब किया गया, Unix सेकंड में
`X-Nimbopanel-Signature`	`sha256=` के बाद हस्ताक्षर (नीचे)
`Content-Type`	`application/json`
`User-Agent`	`Nimbopanel-Webhook/1`

हस्ताक्षर जाँचें

कोई भी आपके पते पर अनुरोध भेज सकता है। हस्ताक्षर से ही आप जानते हैं कि कॉल आपके पैनल से आई है।

हस्ताक्षर टाइमस्टैम्प, एक बिंदु और प्राप्त हुई कच्ची बॉडी, ठीक जैसी है वैसी, का HMAC-SHA256 है, hex में, आपके साइनिंग सीक्रेट से बना हुआ:

X-Nimbopanel-Signature == "sha256=" + hex( HMAC_SHA256( secret, X-Nimbopanel-Timestamp + "." + body ) )

इसे इस क्रम में जाँचें:

ऊपर का मान कच्ची अनुरोध बॉडी से निकालें (किसी भी JSON पार्सिंग या पुनः फ़ॉर्मेटिंग से पहले)।
उसकी हेडर से constant-time तुलना करें।
अगर टाइमस्टैम्प आपकी घड़ी से 5 मिनट से अधिक दूर है तो कॉल अस्वीकार करें। इससे कोई पुरानी कॉल दोबारा नहीं चला सकता।
जिस डिलीवरी को आप सँभाल चुके हैं उसे अनदेखा करने के लिए X-Nimbopanel-Delivery का उपयोग करें।

PHP में उदाहरण:

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_NIMBOPANEL_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_NIMBOPANEL_SIGNATURE'] ?? '';
$want = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($want, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(401);
    exit;
}

Node.js में उदाहरण:

const crypto = require('crypto');
function valid(rawBody, headers, secret) {
  const ts = headers['x-nimbopanel-timestamp'] || '';
  const want = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const got = headers['x-nimbopanel-signature'] || '';
  return got.length === want.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))
    && Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
}

जवाब, पुनः प्रयास और रोकना

10 सेकंड के भीतर किसी भी 2xx स्टेटस से जवाब दें। इसके अलावा कुछ भी विफलता गिना जाता है।
विफल कॉल 1 मिनट बाद फिर आज़माई जाती है, फिर 5 मिनट, 30 मिनट और 2 घंटे बाद। यह कुल पाँच प्रयास हैं, लगभग ढाई घंटे में फैले, और उसके बाद डिलीवरी विफल चिह्नित कर दी जाती है।
एक पते पर कॉल एक-एक करके, सबसे पुरानी पहले, भेजी जाती हैं। पुनः प्रयास की प्रतीक्षा कर रही डिलीवरी नई डिलीवरी को नहीं रोकती, इसलिए घटनाओं के कड़े क्रम में पहुँचने पर भरोसा न करें। धीमा पता केवल खुद को रोकता है।
लगातार 50 विफल डिलीवरी के बाद वेबहुक रुक जाता है: उसके लिए नई घटनाएँ कतार में नहीं डाली जातीं। सफल टेस्ट गिनती साफ़ कर देता है और घटनाएँ फिर बहने लगती हैं।
एक वेबहुक के लिए अधिकतम 200 अनडिलीवर्ड कॉल प्रतीक्षा में रह सकती हैं। उससे ज़्यादा होने पर, कुछ के डिलीवर होने या विफल होने तक उसकी और घटनाएँ कतार में नहीं डाली जातीं।
पैनल हर वेबहुक की सबसे नई 50 पूरी हुई डिलीवरी, मिले जवाब के साथ, रखता है ताकि आप देख सकें कि क्या विफल हुआ। सबसे हाल की वेबहुक के नीचे सूचीबद्ध होती हैं।

अगर पैनल स्टेटस की जगह कोई कारण दिखाता है, तो वह इनमें से एक है: पता सार्वजनिक इंटरनेट पर नहीं है, 10 सेकंड में कोई उत्तर नहीं, होस्ट नाम मौजूद नहीं है, HTTPS प्रमाणपत्र मान्य नहीं है, या पैनल कनेक्ट नहीं हो सका।

अच्छी आदतें

200 से जल्दी जवाब दें और असली काम बाद में करें। जो रिसीवर 10 सेकंड से ज़्यादा लेता है वह विफलता जैसा दिखता है, और उसे वही घटना फिर मिलती है।
एक ही डिलीवरी को दो बार सँभालना हानिरहित रखें। पुनः प्रयास और नेटवर्क त्रुटियाँ डुप्लिकेट संभव बनाती हैं।
सीक्रेट को अपने कोड रिपॉज़िटरी से बाहर रखें। अगर वह लीक हो जाए, तो वेबहुक हटाकर नया जोड़ें।

संबंधित: रीसेलर गाइड · समस्या निवारण