POST /apiv2/reports/webhooks

ایک URL رجسٹر کریں اور جب کوئی رپورٹ تیار ہوگی تو NETTS آپ کے اسٹیٹس چیک کرنے کے بجائے خود اس URL کو کال کرے گا۔

یہ اینڈ پوائنٹس آرڈر ویب ہکس سے الگ ہیں۔ وہاں رجسٹر کرنے سے آپ رپورٹ کے نوٹیفیکیشنز کے لیے سبسکرائب نہیں ہوتے، اور اسی طرح اس کے برعکس بھی ہے۔ وائر فارمیٹ — دستخط (signature)، ہیڈرز، دوبارہ کوشش کا طریقہ کار (retry behaviour) — بالکل یکساں ہے، لہذا ایک کے لیے لکھا گیا ہینڈلر دوسرے کے لیے بھی کام کرتا ہے۔

اینڈ پوائنٹ بنیادی URL

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

درخواست کے ہیڈرز

ہیڈر	درکار ہے	تفصیل
X-API-KEY	ہاں	ڈیش بورڈ سے API کلید
X-Real-IP	ہاں	کلید کی وائٹ لسٹ سے ایک پتہ

بنیادی اور بیک اپ

فی اکاؤنٹ دو اینڈ پوائنٹس تک کی اجازت ہے۔ 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 کے اندر اسناد (credentials) بھی۔ کوئی بھی مسترد شدہ چیز وجہ کے ساتھ 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	ڈپلیکیٹ ہٹانے کی کلید (Dedup key)۔ 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 کے ذریعے ڈپلیکیٹ کی شناخت کریں۔ آپ کی طرف سے دہرائے گئے عمل پر کوئی کارروائی نہیں ہونی چاہیے۔
2. کارروائی کرنے سے پہلے دستخط کی تصدیق کریں، بعد میں نہیں۔
3. صرف ایونٹ محفوظ کرنے کے بعد 2xx جواب دیں۔ کوئی بھی دوسری چیز، یا ٹائم آؤٹ، ناکامی سمجھی جائے گی اور دوبارہ کوشش کی جائے گی۔

ایک اینڈ پوائنٹ پر دوبارہ کوششیں 1 منٹ، 5 منٹ، 15 منٹ، 1 گھنٹہ، 6 گھنٹے اور 24 گھنٹے پر کی جاتی ہیں — کل چھ کوششیں، جو کہ تقریباً 31 گھنٹوں سے کچھ زائد پر محیط ہوتی ہیں۔ جب وہ ختم ہو جائیں اور آپ نے ایک backup رجسٹر کیا ہو، تو ترسیل وہاں منتقل ہو جاتی ہے اور شیڈول بیک اپ کے اپنے خفیہ کوڈ کے ساتھ دوبارہ شروع ہوتا ہے۔ delivery_id شروع سے آخر تک یکساں رہتی ہے، لہذا ایسا ایونٹ جو بنیادی پر ناکام ہوا اور بیک اپ پر کامیاب ہوا، وہ بدستور ایک ہی ایونٹ ہوتا ہے۔

ری ڈائریکٹس کی پیروی نہیں کی جاتی ہے۔

شرح کی حدیں

فی اینڈ پوائنٹ 10 درخواستیں فی سیکنڈ، تمام کلائنٹس کے درمیان مشترک۔

خرابیاں

رجسٹریشن پر 201 جواب آتا ہے، حذف کرنے پر بغیر باڈی کے 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 اور ایکٹیویشن کے ایونٹس کے لیے علیحدہ رجسٹری