POST /apiv2/reports/webhooks

एक URL पंजीकृत करें और रिपोर्ट तैयार होने पर NETTS उसे कॉल करेगा, बजाय इसके कि आप स्थिति की जाँच (polling) करते रहें।

ये एंडपॉइंट ऑर्डर वेबहुक से अलग हैं। वहाँ पंजीकरण करने से आप रिपोर्ट सूचनाओं की सदस्यता नहीं लेते हैं, और इसके विपरीत भी ऐसा ही है। वायर प्रारूप — हस्ताक्षर (signature), शीर्षलेख (headers), पुनः प्रयास व्यवहार (retry behaviour) — समान है, इसलिए एक के लिए लिखा गया हैंडलर दूसरे के लिए भी काम करता है।

एंडपॉइंट बेस URL

https://netts.io/apiv2/reports/webhooks

अनुरोध शीर्षलेख

शीर्षलेख	आवश्यक	विवरण
X-API-KEY	हाँ	डैशबोर्ड से प्राप्त API कुंजी
X-Real-IP	हाँ	कुंजी श्वेतसूची (whitelist) से एक पता

प्राथमिक और बैकअप

प्रति खाता अधिकतम दो एंडपॉइंट। primary को सब कुछ प्राप्त होता है। backup का उपयोग केवल तभी किया जाता है जब प्राथमिक पर डिलीवरी के सभी प्रयास समाप्त हो जाते हैं — और इसे इसके अपने गुप्त कोड (secret) के साथ हस्ताक्षरित किया जाता है, प्राथमिक के कोड के साथ नहीं।

पंजीकरण करें

curl -s -X POST 'https://netts.io/apiv2/reports/webhooks' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/netts/reports", "role": "primary"}'

{
  "status": "success",
  "code": 10000,
  "data": {
    "id": 1,
    "url": "https://example.com/netts/reports",
    "role": "primary",
    "is_active": true,
    "created_at": "2026-09-06 17:05:12+00:00",
    "updated_at": "2026-09-06 17:05:12+00:00",
    "secret": "whsec_<64 hex characters>"
  }
}

गुप्त कोड (secret) केवल एक बार, यहीं दिखाया जाता है। यह फिर कभी वापस नहीं दिया जाता — न तो सूची द्वारा, न ही रीड एंडपॉइंट द्वारा। इसे प्राप्त होते ही सुरक्षित रख लें। यदि यह खो जाता है, तो नया जारी करें:

curl -s -X POST 'https://netts.io/apiv2/reports/webhooks/1/rotate-secret' \
  -H 'X-API-KEY: your-api-key' -H 'X-Real-IP: 203.0.113.10'

रोटेशन तुरंत प्रभावी होता है और पुराना गुप्त कोड सत्यापन करना बंद कर देता है, इसलिए यदि आप किसी रुकावट को बर्दाश्त नहीं कर सकते हैं तो पहले नया मान लागू करें।

प्रबंधन करें

विधि	पथ	कार्रवाई
GET	/apiv2/reports/webhooks	अपने एंडपॉइंट सूचीबद्ध करें, बिना गुप्त कोड के
GET	/apiv2/reports/webhooks/{id}	एक को पढ़ें
PATCH	/apiv2/reports/webhooks/{id}	url बदलें, या is_active: false के साथ रोकें
DELETE	/apiv2/reports/webhooks/{id}	इसे हटाएँ

URL सार्वजनिक HTTPS होना चाहिए। लूपबैक, निजी और लिंक-लोकल पते अस्वीकार कर दिए जाते हैं, जैसा कि URL के अंदर के क्रेडेंशियल भी। अस्वीकृत होने वाली कोई भी चीज़ कारण के साथ 422 के रूप में वापस आती है। यह जाँच प्रत्येक डिलीवरी से ठीक पहले फिर से चलती है, इसलिए कोई एंडपॉइंट जो बाद में किसी निजी पते पर रिज़ॉल्व होता है, वह प्राप्त करना बंद कर देता है।

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

{
  "event": "report.ready",
  "delivery_id": 4,
  "order_id": "REPxxxxxxxxxxxx",
  "order_type": "statement",
  "client_request_id": "stmt-2026-09-usdt",
  "status": "done",
  "format": "csv",
  "download_url": "/apiv2/reports/REPxxxxxxxxxxxx/download",
  "expires_at": "2026-10-06 15:48:04+00:00",
  "artifact": { "sha256": "…", "size_bytes": 696 },
  "confirmed_at": "2026-09-06T15:48:04Z"
}

फ़ील्ड	विवरण
event	report.ready — आपके हैंडलर के लिए रूटिंग कुंजी
delivery_id	डीडुप्लिकेट कुंजी। इसे X-Netts-Delivery शीर्षलेख के रूप में भी भेजा जाता है
order_id	जब आपने रिपोर्ट को कतारबद्ध किया था तब आपको दिया गया ऑर्डर नंबर
order_type	statement या balance_at_date
download_url	https://netts.io के सापेक्ष फ़ाइल प्राप्त करने का पथ
artifact.sha256	चेकसम, ताकि आप डाउनलोड की गई सामग्री को सत्यापित कर सकें
confirmed_at	UTC

सभी टाइमस्टैम्प UTC हैं।

हस्ताक्षर सत्यापित करना

X-Netts-Signature: sha256=<hex>
X-Netts-Timestamp: <unix seconds>
X-Netts-Delivery:  <delivery_id>

हस्ताक्षर "<timestamp>." + raw body पर HMAC-SHA256 है, जिसकी गणना उस एंडपॉइंट के गुप्त कोड के साथ की जाती है जिसने अनुरोध प्राप्त किया था। स्थिर समय (constant time) में तुलना करें और ऐसे किसी भी अनुरोध को अस्वीकार करें जिसका टाइमस्टैम्प ±5 मिनट की विंडो से बाहर आता है।

import hmac, hashlib, time

def verify(raw_body: bytes, sig_header: str, ts_header: str, secret: str) -> bool:
    if abs(time.time() - int(ts_header)) > 300:      # anti-replay
        return False
    signed = f"{ts_header}.".encode() + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig_header)

उस URL के गुप्त कोड के साथ हस्ताक्षर करें जिस पर अनुरोध आया था: प्राथमिक और बैकअप के अलग-अलग गुप्त कोड होते हैं।

डिलीवरी कम से कम एक बार (at-least-once) होती है

किसी प्रतिक्रिया के छूट जाने पर पुनः प्रयास किया जाता है, इसलिए एक ही घटना दो बार आ सकती है।

1. delivery_id द्वारा डीडुप्लिकेट करें। दोहराव आपके पक्ष में एक नो-ऑप (no-op) होना चाहिए।
2. कार्रवाई करने से पहले हस्ताक्षर सत्यापित करें, बाद में नहीं।
3. घटना को संग्रहीत करने के बाद ही 2xx उत्तर दें। कुछ भी अन्य, या टाइमआउट, एक विफलता माना जाता है और पुनः प्रयास किया जाता है।

एक एंडपॉइंट पर पुनः प्रयास 1 मिनट, 5 मिनट, 15 मिनट, 1 घंटा, 6 घंटे और 24 घंटे पर होते हैं — कुल छह प्रयास, जो 31 घंटे से थोड़े अधिक समय तक चलते हैं। जब वे समाप्त हो जाते हैं और आपने एक backup पंजीकृत किया है, तो डिलीवरी वहाँ स्थानांतरित हो जाती है और शेड्यूल बैकअप के अपने गुप्त कोड के साथ फिर से शुरू होता है। delivery_id पूरे समय समान रहता है, इसलिए प्राथमिक पर विफल होने वाली और बैकअप पर सफल होने वाली घटना अभी भी एक ही घटना है।

रीडायरेक्ट का पालन नहीं किया जाता है।

दर सीमाएं

प्रति एंडपॉइंट 10 अनुरोध प्रति सेकंड, जो सभी ग्राहकों में साझा किए जाते हैं।

त्रुटियाँ

पंजीकरण पर 201 उत्तर मिलता है, हटाने पर बिना किसी मुख्य भाग (body) के 204, बाकी सब कुछ 200।

HTTP	अर्थ
401	कुंजी गायब या अमान्य है, या स्रोत IP श्वेतसूची में नहीं है
404	आपके खाते पर ऐसा कोई एंडपॉइंट नहीं है
409	अनुरोधित भूमिका पहले से ही ली जा चुकी है — role primary is already taken
422	URL अस्वीकार कर दिया गया था, या एक PATCH बॉडी में बदलने के लिए कुछ भी नहीं था
429	दर सीमा पार हो गई

एक अस्वीकृत URL कारण स्पष्ट करते हुए 422 के रूप में वापस आता है, ताकि आप इसे उसे दिखा सकें जिसने इसे टाइप किया था:

{"status": "error", "code": -4, "msg": "url: Value error, invalid webhook_url: resolved address 127.0.0.1 is not public"}

शब्दावली only https:// URLs are allowed, credentials in URL are not allowed, और resolved address <ip> is not public हैं। अंतिम वाला पंजीकरण के समय और प्रत्येक डिलीवरी से ठीक पहले फिर से रिज़ॉल्व किया जाता है, इसलिए एक होस्टनाम जो बाद में किसी निजी पते को इंगित करता है, वह प्राप्त करना बंद कर देता है।

संबंधित

• स्टेटमेंट फ़ाइलें — उस रिपोर्ट का ऑर्डर देना जो इस सूचना को ट्रिगर करती है
• ऑर्डर वेबहुक — Energy, Bandwidth और सक्रियण घटनाओं के लिए अलग रजिस्ट्री