वेबहुक

आपके खाते का एक ही वेबहुक URL होता है और सभी घटनाएँ वहीं भेजी जाती हैं। इसे Dashboard → API में या वेबहुक कॉन्फ़िगर करें से सेट करें।

घटनाएँ

आज छह घटनाएँ मौजूद हैं।

घटना	कब भेजी जाती है
`order.updated`	एनर्जी या बैंडविड्थ ऑर्डर की स्थिति बदलने पर — केवल API से बनाए गए ऑर्डर के लिए
`subscription.transfer`	Smart Mode ने किसी निगरानी वाले पते से हुए ट्रांसफ़र का भुगतान किया
`package.transfer`	Transfer Package ने अपने पते से हुए ट्रांसफ़र का भुगतान किया
`package.completed`	Transfer Package ने ट्रांसफ़र की सेवा बंद कर दी
`package.activated`	Transfer Package सक्रिय हुआ
`package.expired`	बिना भुगतान वाले Transfer Package इनवॉइस की अवधि समाप्त हुई

order.updated केवल उन ऑर्डर के लिए भेजी जाती है जो API कुंजी से बनाए गए हों। वेबसाइट या टेलीग्राम बॉट से की गई खरीद पर कोई वेबहुक नहीं जाता — भले ही वही खाता Smart Mode की घटनाएँ सामान्य रूप से पाता रहे।

लिफ़ाफ़ा

हर डिलीवरी में वही तीन शीर्ष-स्तरीय कुंजियाँ होती हैं। timestamp वह क्षण है जब हमने घटना बनाई — ISO-8601, UTC में।

Response

{
  "event": "order.updated",
  "data": { },
  "timestamp": "2026-09-14T14:51:16.986341+00:00"
}

हेडर:

हेडर	मान
`Content-Type`	`application/json`
`X-Webhook-Signature`	`sha256=<hex>` — नीचे «हस्ताक्षर की जाँच» देखें
`Host`	आपके URL का होस्ट

`order.updated`

number

ऑर्डर ID।

string

energy या bandwidth।

string

processing, filled, partial, failed, reclaimed या reclaim_failed। यही फ़ील्ड सत्य का स्रोत है — नीचे दी चेतावनी देखें।

string

वह पता जिसे संसाधन डेलिगेट किया गया।

number

ऑर्डर की गई मात्रा — एनर्जी यूनिट या बैंडविड्थ पॉइंट।

number

volume जैसा ही। यह इसलिए है कि अपेक्षित और वितरित की तुलना बिना यह जाने की जा सके कि कौन-सा फ़ील्ड क्या दर्शाता है।

number

अब तक वास्तव में कितना डेलिगेट हुआ। ऑर्डर filled होने पर volume के बराबर; processing और partial में अब तक दिए गए हिस्सों का योग; विफलता पर 0।

string

ऑर्डर की कीमत TRX में, दशमलव स्ट्रिंग के रूप में।

string | null

वह लेनदेन जिसने संसाधन डेलिगेट किया।

string | null

वह लेनदेन जिसने किराया समाप्त होने पर उसे वापस लिया।

string | null

संसाधन कब वापस लिया जाना है, ISO-8601; टाइमर से वापस न लिए जाने वाले ऑर्डर में null।

Response

{
  "event": "order.updated",
  "data": {
    "id": 247033,
    "type": "energy",
    "status": "filled",
    "target_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "volume": 65000,
    "expected_volume": 65000,
    "delivered_volume": 65000,
    "price_trx": "2.75",
    "delegate_txid": "a1b2c3d4e5f6...",
    "undelegate_txid": null,
    "reclaim_at": "2026-09-15T07:44:56+00:00"
  },
  "timestamp": "2026-09-14T14:51:16.986341+00:00"
}

परिणाम status से आँकें, delegate_txid की मौजूदगी से नहीं। विफल ऑर्डर में भी लेनदेन ID हो सकता है — हम उसे जानबूझकर रखते हैं ताकि विफलता की जाँच हो सके। संसाधन मिला या नहीं, यह केवल status बताता है।

बड़े ऑर्डर को हम भीतर हिस्सों में बाँटते हैं, पर वह हमारा काम है: आपको प्रति ऑर्डर एक ही वेबहुक मिलता है, प्रति हिस्सा नहीं।

`subscription.transfer`

number

वह Smart Mode सब्सक्रिप्शन जिससे यह ट्रांसफ़र जुड़ा है।

string

वह निगरानी वाला पता जहाँ से ट्रांसफ़र गया।

string | null

आपने सब्सक्रिप्शन को जो लेबल दिया।

string

चेन पर ट्रांसफ़र का लेनदेन।

number

इस डेलिगेशन ने कितने ट्रांसफ़र कवर किए।

number

उनके लिए डेलिगेट की गई एनर्जी।

string

एनर्जी के लिए काटी गई राशि, TRX में।

string | null

ऊपर से काटा गया बैंडविड्थ, या न काटे जाने पर null।

string

कटौती के बाद आपके खाते का बैलेंस।

string

ट्रांसफ़र कब संसाधित हुआ। ध्यान दें कि यह data के भीतर है और लिफ़ाफ़े के अपने timestamp से अलग है।

Response

{
  "event": "subscription.transfer",
  "data": {
    "subscription_id": 412,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "label": "payouts",
    "tx_hash": "9f8e7d6c5b4a...",
    "transfer_count": 1,
    "energy_delegated": 65000,
    "fee_trx": "2.75",
    "bw_fee_trx": null,
    "balance_after_trx": "376.63",
    "timestamp": "2026-09-14T14:51:16.512033+00:00"
  },
  "timestamp": "2026-09-14T14:51:16.986341+00:00"
}

Transfer Package घटनाएँ

चारों package.* घटनाएँ उस खाते को जाती हैं जो पैकेज का मालिक है। साइन इन किए बिना या API कुंजी के बिना इनवॉइस से खरीदे गए पैकेज का कोई मालिक नहीं होता, और उससे कोई घटना नहीं बनती। रद्द किए गए इनवॉइस, अस्वीकृत खरीद और मैन्युअल समीक्षा में रुकी खरीद से भी कोई घटना नहीं बनती; समीक्षा वाला पैकेज सक्रिय होने पर package.activated भेजता है। हर package.* घटना के data में ये फ़ील्ड होते हैं:

number

पैकेज ID — पैकेज सूची में id।

string

वह पता जिसकी सेवा पैकेज करता है।

string

घटना के बाद पैकेज की स्थिति: package.transfer के लिए active या completed, package.completed के लिए completed, package.activated के लिए active, package.expired के लिए expired।

number

पैकेज कितने ट्रांसफ़र के साथ खरीदा गया था।

number

घटना जिस बदलाव की सूचना देती है, उसके बाद इस पैकेज में बचे ट्रांसफ़र — एक निरपेक्ष संख्या, अंतर नहीं।

घटनाएँ क्रम से बाहर आ सकती हैं। हर घटना अलग से भेजी जाती है और लगभग 35 सेकंड तक दोबारा कोशिश होती है, इसलिए किसी ट्रांसफ़र से हुई package.completed उसी ट्रांसफ़र की package.transfer से पहले आ सकती है, और package.transfer package.activated से पहले आ सकती है। हर package_id के लिए अब तक देखा गया सबसे कम remaining रखें: यह कभी नहीं बढ़ता। completed और expired अंतिम हैं।

remaining बिना किसी घटना के भी घट सकता है। कई ट्रांसफ़र वाला पैकेज दैनिक सदस्यता के रूप में दिन में एक ट्रांसफ़र लेता है — पहला सक्रिय होते समय, इसीलिए 500 ट्रांसफ़र वाला पैकेज remaining: 499 से शुरू होता है — और इस कटौती की अलग सूचना नहीं आती। एक ही पते से एक ही ब्लॉक में हुए दो ट्रांसफ़र एक जैसा remaining बता सकते हैं। remaining को संकेत मानें और पैकेज सूची को सच्चाई का स्रोत।

दोबारा भेजी गई घटना पहचानने के लिए package.transfer में (package_id, tx_hash) और बाकी में (event, package_id) का उपयोग करें: दोबारा भेजी गई घटना में वही बॉडी, वही timestamp और वही हस्ताक्षर होते हैं।

`package.transfer`

पते से हुए ट्रांसफ़र का भुगतान पैकेज से हुआ। ट्रांसफ़र जिस हर पैकेज से काटा गया, उसके लिए एक बार भेजी जाती है — लगभग हमेशा प्रति ट्रांसफ़र एक घटना; जो ट्रांसफ़र एक पैकेज का आख़िरी ट्रांसफ़र लेकर अगले पैकेज पर जारी रहता है, वह दोनों के लिए एक-एक घटना देता है।

string

चेन पर ट्रांसफ़र का ट्रांज़ैक्शन।

number

इस ट्रांज़ैक्शन के लिए इस पैकेज से काटे गए ट्रांसफ़र। ऐसे पते पर ट्रांसफ़र जिसके पास USDT नहीं है, दोगुनी ऊर्जा लेता है और 2 गिना जाता है, जो दो पैकेजों में बँट सकता है।

यहाँ अगर इस ट्रांसफ़र ने पैकेज खत्म कर दिया तो status completed होता है।

Response

{
  "event": "package.transfer",
  "data": {
    "package_id": 318,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "active",
    "quota_total": 500,
    "remaining": 312,
    "tx_hash": "9f8e7d6c5b4a...",
    "units": 1
  },
  "timestamp": "2026-10-15T14:51:16.986341+00:00"
}

`package.completed`

पैकेज ने ट्रांसफ़र की सेवा बंद कर दी।

string

transfer — एक ट्रांसफ़र ने पैकेज खत्म किया; subscription — दैनिक कटौती ने उसे खत्म किया; manual — सपोर्ट ने पैकेज बंद किया। manual के बाद remaining शून्य से अधिक हो सकता है, लेकिन वे ट्रांसफ़र अब उपयोग नहीं किए जा सकते।

string | null

reason: "transfer" होने पर वह ट्रांसफ़र जिसने पैकेज बंद किया; अन्यथा null।

बिना शेष वाला पैकेज — जैसे एक ट्रांसफ़र वाला सामान्य पैकेज, जिसकी पहली दैनिक कटौती ने उसका इकलौता ट्रांसफ़र ले लिया — अगले ट्रांसफ़र से अपनी package.transfer के बिना बंद हो जाता है: आपको उस ट्रांसफ़र के tx_hash के साथ केवल package.completed मिलती है।

Response

{
  "event": "package.completed",
  "data": {
    "package_id": 318,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "completed",
    "quota_total": 500,
    "remaining": 0,
    "reason": "transfer",
    "tx_hash": "9f8e7d6c5b4a..."
  },
  "timestamp": "2026-10-15T14:51:16.986341+00:00"
}

`package.activated`

पैकेज सक्रिय हो गया और अब से उसके ट्रांसफ़र को ऊर्जा मिलती है। हर सक्रियण पर भेजी जाती है — बैलेंस से खरीद पर भी, जिसका जवाब पहले से active कहता है, और इनवॉइस भुगतान पर भी, जो चेन पर भुगतान दिखने के थोड़ी देर बाद पैकेज सक्रिय करता है।

string

पैकेज का भुगतान कैसे हुआ: ठीक balance, TRX या USDT।

Response

{
  "event": "package.activated",
  "data": {
    "package_id": 318,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "active",
    "quota_total": 500,
    "remaining": 499,
    "payment_method": "USDT"
  },
  "timestamp": "2026-10-15T14:51:16.986341+00:00"
}

`package.expired`

पैकेज का इनवॉइस अपनी 30 मिनट की अवधि में नहीं चुकाया गया। कुछ नहीं काटा गया; नया इनवॉइस पाने के लिए फिर से खरीदें। कोई अतिरिक्त फ़ील्ड नहीं; remaining quota_total के बराबर है और उपयोग के लिए उपलब्ध नहीं है।

Response

{
  "event": "package.expired",
  "data": {
    "package_id": 319,
    "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "expired",
    "quota_total": 500,
    "remaining": 500
  },
  "timestamp": "2026-10-15T15:21:16.986341+00:00"
}

डिलीवरी

अधिकतम 3 प्रयास, बीच में 1 सेकंड और फिर 4 सेकंड का ठहराव। सफलता के बाद और अंतिम प्रयास के बाद कोई ठहराव नहीं।
प्रति प्रयास 10 सेकंड का टाइमआउट।
हम कोई भी 2xx स्वीकार करते हैं। बाकी सब विफल प्रयास गिना जाता है।
रीडायरेक्ट का पालन नहीं किया जाता। 301/302 एक विफल प्रयास है, छलाँग नहीं।
छूटी हुई घटनाएँ बाद में दोबारा नहीं भेजी जातीं। तीनों प्रयास विफल हुए तो वह घटना चली गई; दोबारा भेजे जाने की प्रतीक्षा के बजाय ऑर्डर देखें या पैकेज सूची से मिलान करें।

आपका URL किसी सार्वजनिक पते पर रिज़ॉल्व होना चाहिए। लूपबैक, निजी और लिंक-लोकल रेंज अस्वीकार की जाती हैं, और वह होस्ट भी जो रिज़ॉल्व ही न हो — दोनों स्थितियों में कुछ नहीं भेजा जाता और लॉग में कोई पंक्ति नहीं लिखी जाती।

हस्ताक्षर की जाँच

हर अनुरोध में X-Webhook-Signature: sha256=<hex> होता है — आपके वेबहुक सीक्रेट से, कच्चे अनुरोध बॉडी पर निकाला गया HMAC-SHA256। आपकी जाँच चलेगी या नहीं, यह दो बातों पर निर्भर है:

तुलना से पहले sha256= उपसर्ग हटाएँ। हेडर केवल हेक्स डाइजेस्ट नहीं है।
प्राप्त बाइट्स का हैश लें, दोबारा सीरियलाइज़ किए गए ऑब्जेक्ट का नहीं। JSON को पार्स करके फिर से लिखने पर कुंजियों का क्रम और स्पेस बदल जाते हैं, और हस्ताक्षर कभी नहीं मिलेगा।

आपका साइनिंग सीक्रेट Dashboard → API में वेबहुक URL के बगल में दिखता है। API कुंजी वाले अनुरोधों को यह नहीं लौटाया जाता — पढ़ने के लिए वेबसाइट पर साइन इन करना होगा।

import hashlib
import hmac

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    prefix, _, received = signature_header.partition("=")
    if prefix != "sha256" or not received:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)

const crypto = require("crypto");

function verifyWebhook(rawBody, signatureHeader, secret) {
  const [prefix, received] = String(signatureHeader).split("=");
  if (prefix !== "sha256" || !received) return false;
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

सामग्री पर कार्रवाई करने से पहले हस्ताक्षर जाँचें, और स्थिर समय में तुलना करें (hmac.compare_digest / crypto.timingSafeEqual)। == से तुलना समय के ज़रिए जानकारी लीक करती है।

मुख्य API

बैंडविड्थ रेंटल (ऑटो-रिन्यू)

ऑटो रिफिल

ऑर्डर

इनवॉइस

Smart Mode

ट्रांसफर पैकेज

खाता

Webhooks

वेबहुक — परिचय