ویب ہکس — آرڈر کی اطلاعات

ایک HTTPS اینڈ پوائنٹ رجسٹر کریں تاکہ جس لمحے آپ کا کوئی آرڈر آن چین مکمل اور تصدیق شدہ ہو جائے، اسی وقت ایک دستخط شدہ ویب ہک موصول ہو سکے۔ پولنگ کے بجائے، آپ اطلاع موصول ہوتے ہی اپنا عمل (مثلاً USDT جاری کرنا) جاری رکھ سکتے ہیں۔

تین واقعات (events) بھیجے جاتے ہیں:

واقعہ	اس وقت بھیجا جاتا ہے جب
`delegation.confirmed`	ایک Energy کرایہ پر لینا (`1h` / `5m`) آن چین تصدیق شدہ ہو
`bandwidth.delegated`	ایک Bandwidth آرڈر مکمل ہو جائے
`activation.confirmed`	ایک ایڈریس ایکٹیویشن آن چین انجام پا جائے

یہ صفحہ مینجمنٹ API (اپنے اینڈ پوائنٹس بنانا / فہرست دیکھنا / ترمیم کرنا / secret تبدیل کرنا / حذف کرنا) اور ان ویب ہکس کے فارمیٹ کا احاطہ کرتا ہے جو ہم آپ کو بھیجتے ہیں۔

ℹ️ کردار۔ آپ اپنے اینڈ پوائنٹس کا انتظام یہاں کرتے ہیں۔ ترسیل آرڈر کی تصدیق کے بعد Netts کی جانب سے غیر مطابقت پذیر (asynchronously) طور پر کی جاتی ہے — پول کرنے کے لیے کچھ نہیں ہے۔ صرف کامیابی کے واقعات بھیجے جاتے ہیں؛ ناکامیاں اور ٹائم آؤٹ کبھی ڈیلیور نہیں کیے جاتے۔

🔒 ہر ہیش جو ہم بھیجتے ہیں پہلے آن چین تصدیق شدہ ہوتا ہے۔ ایک ویب ہک صرف اسی وقت روانہ کیا جاتا ہے جب اس میں موجود ہر ٹرانزیکشن ہیش کسی بلاک میں مل جائے۔ اگر کوئی ہیش ابھی تک کسی بلاک میں نہیں ہے، تو ترسیل روک دی جاتی ہے اور 5 منٹ تک ہر 30 سیکنڈ بعد دوبارہ جانچ کی جاتی ہے؛ اگر یہ کبھی شامل نہ ہو، تو اس آرڈر کے لیے کچھ نہیں بھیجا جاتا۔ آپ کو کبھی ایسا ہیش موصول نہیں ہوگا جو آن چین موجود نہ ہو۔

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

https://netts.io/apiv2/webhooks

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

ہیڈر	لازمی	تفصیل
Content-Type	ہاں (POST/PATCH کے لیے)	application/json
X-API-KEY	ہاں	Netts ڈیش بورڈ سے آپ کی API کلید
X-Real-IP	ہاں	آپ کی وائٹ لسٹ سے IP ایڈریس

آپ کا user_id آپ کی API کلید سے اخذ کیا جاتا ہے — آپ کو اسے کبھی پاس کرنے کی ضرورت نہیں ہوتی۔ آپ صرف اپنے اینڈ پوائنٹس دیکھ اور تبدیل کر سکتے ہیں۔

بنیادی اور بیک اپ اینڈ پوائنٹ

آپ زیادہ سے زیادہ دو اینڈ پوائنٹس رجسٹر کر سکتے ہیں، اور ہر ایک کا ایک role ہوتا ہے:

کردار	مقصد
`primary`	وہ ایڈریس جس پر ہر ویب ہک ڈیلیور کیا جاتا ہے۔
`backup`	فال بیک۔ صرف اسی وقت استعمال ہوتا ہے جب دوبارہ کوششوں (retries) کے ختم ہونے کے بعد `primary` پر ترسیل ناکام ہو جائے۔

ایک واحد تصدیق شدہ آرڈر ایک واحد ویب ہک تیار کرتا ہے۔ یہ فین آؤٹ (fan-out) نہیں ہے: ایک ہی واقعہ کبھی بھی بیک وقت دونوں پتوں پر نہیں بھیجا جاتا۔ backup اینڈ پوائنٹ لچک اور تسلسل کے لیے موجود ہے — اگر آپ کا بنیادی ہوسٹ ناقابل رسائی ہے یا مسلسل غیر 2xx کوڈ واپس کر رہا ہے، تو ترسیل ضائع ہونے کے بجائے بیک اپ کی طرف منتقل ہو جاتی ہے۔

پہلا اینڈ پوائنٹ جو آپ بناتے ہیں وہ primary بن جاتا ہے، دوسرا backup بن جاتا ہے۔ آپ واضح طور پر role پاس کر سکتے ہیں، یا بعد میں PATCH کے ذریعے انہیں تبدیل کر سکتے ہیں۔

ہر آپریشن کی قسم کے لیے الگ URL کیوں نہیں؟ کیونکہ واقعے کی قسم باڈی کے اندر، event فیلڈ میں منتقل ہوتی ہے۔ ایک ہی ہینڈلر، ایک ہی دستخط کی تصدیق، اور آپ کو بغیر کچھ نیا رجسٹر کیے واقعات کی نئی اقسام موصول ہونا شروع ہو جاتی ہیں۔

اینڈ پوائنٹس کا انتظام کریں

بنائیں — `POST /apiv2/webhooks`

ایک نیا اینڈ پوائنٹ رجسٹر کرتا ہے اور ایک secret واپس کرتا ہے جو صرف ایک بار دکھایا جاتا ہے (اسے محفوظ کر لیں — یہ آپ کو موصول ہونے والے ہر ویب ہک پر دستخط کرتا ہے)۔

json

// request body — role is optional
{
    "url": "https://your-server.example/netts/delegation-hook",
    "role": "primary"
}

اگر آپ role چھوڑ دیتے ہیں، تو پہلا دستیاب تفویض کر دیا جاتا ہے: پہلے primary، پھر backup۔

json

// response 201
{
    "detail": {
        "code": 10000,
        "status": "created",
        "data": {
            "id": 1,
            "url": "https://your-server.example/netts/delegation-hook",
            "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "role": "primary",
            "is_active": true,
            "created_at": "2026-01-01T00:00:00"
        }
    }
}

URL کے تقاضے (بنانے پر اور ہر ترمیم پر تصدیق کی جاتی ہے):

لازمی طور پر https ہونا چاہیے؛
لازمی طور پر عوامی ایڈریس پر ریزولول (resolve) ہونا چاہیے — لوپ بیک، پرائیویٹ (RFC1918)، لنک لوکل (بشمول 169.254.169.254)، اور دیگر نان روٹ ایبل رینجز مسترد کر دی جاتی ہیں؛
URL میں کوئی اسناد (credentials) نہیں ہونی چاہئیں (user:pass@…)؛
لمبائی 2048 حروف تک۔

مسترد شدہ URL پر 400 کوڈ ملتا ہے۔

آپ کے پاس دو اینڈ پوائنٹس ہو سکتے ہیں — ایک primary اور ایک backup۔ تیسرا بنانے کی کوشش پر 409 (4090) واپس آتا ہے۔ ایسا role مانگنا جو پہلے ہی تفویض شدہ ہو 409 (4091) واپس کرتا ہے — PATCH کے ساتھ کرداروں کو تبدیل کریں یا پہلے موجودہ کو حذف کریں۔

bash

curl -X POST https://netts.io/apiv2/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{"url": "https://your-server.example/netts/delegation-hook", "role": "primary"}'

فہرست — `GET /apiv2/webhooks`

آپ کے اینڈ پوائنٹس واپس کرتا ہے (یہاں secret کبھی واپس نہیں کیا جاتا)۔

json

{
    "detail": {
        "code": 10000,
        "status": "ok",
        "data": {
            "endpoints": [
                {
                    "id": 1,
                    "url": "https://your-server.example/netts/delegation-hook",
                    "role": "primary",
                    "is_active": true,
                    "created_at": "2026-01-01T00:00:00",
                    "updated_at": "2026-01-01T00:00:00"
                },
                {
                    "id": 2,
                    "url": "https://backup.example/netts/delegation-hook",
                    "role": "backup",
                    "is_active": true,
                    "created_at": "2026-01-01T00:00:00",
                    "updated_at": "2026-01-01T00:00:00"
                }
            ],
            "count": 2,
            "max_endpoints": 2,
            "roles": ["primary", "backup"]
        }
    }
}

ایک حاصل کریں — `GET /apiv2/webhooks/{id}`

فہرست کے آئٹم جیسی ہی ساخت (کوئی secret نہیں)۔ کسی غیر متعلقہ یا غیر موجود id پر 404 ملتا ہے۔

ترمیم کریں — `PATCH /apiv2/webhooks/{id}`

url، is_active اور/یا role کو تبدیل کریں۔ کوئی بھی سب سیٹ بھیجیں؛ خالی باڈی پر 422 کوڈ ملتا ہے۔ تبدیل شدہ url کی دوبارہ توثیق کی جاتی ہے (https / SSRF)۔ غیر متعلقہ یا غیر موجود id پر 404 ملتا ہے۔

json

// request body (any subset)
{ "url": "https://your-server.example/netts/new-hook", "is_active": false }

json

// response 200
{
    "detail": {
        "code": 10000,
        "status": "updated",
        "data": {
            "id": 1,
            "url": "https://your-server.example/netts/new-hook",
            "role": "primary",
            "is_active": false,
            "created_at": "2026-01-01T00:00:00",
            "updated_at": "2026-01-01T00:00:01"
        }
    }
}

بیک اپ کو پرائمری بنانا۔ اپنے بیک اپ اینڈ پوائنٹ کو {"role": "primary"} بھیجنا ایک ہی ٹرانزیکشن میں دونوں کرداروں کو آپس میں تبدیل کر دیتا ہے — پرانا پرائمری اب بیک اپ بن جاتا ہے۔ آپ کبھی بھی بنیادی ایڈریس کے بغیر نہیں رہتے، اور دوسرے اینڈ پوائنٹ کے لیے کسی الگ کال کی ضرورت نہیں ہوتی۔

bash

curl -X PATCH https://netts.io/apiv2/webhooks/2 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key" \
  -H "X-Real-IP: your_whitelisted_ip" \
  -d '{"role": "primary"}'

اینڈ پوائنٹ کو حذف کیے بغیر ترسیل روکنے کے لیے is_active: false مقرر کریں؛ دوبارہ شروع کرنے کے لیے true۔ اپنے primary کو روکنا بیک اپ کو پرائمری نہیں بناتا — ترسیل اب بھی پرائمری کو ہی ہدف بناتی ہے۔ اگر آپ چاہتے ہیں کہ بیک اپ کام سنبھال لے تو کرداروں کو آپس میں تبدیل کریں۔

سیکریٹ تبدیل کریں (Rotate secret) — `POST /apiv2/webhooks/{id}/rotate-secret`

ایک نیا secret بناتا ہے اور اسے ایک بار واپس کرتا ہے۔ نیا سیکریٹ اگلی ترسیلات کے لیے فوری طور پر نافذ العمل ہو جاتا ہے — مزید کسی کارروائی کی ضرورت نہیں ہوتی۔ ہر اینڈ پوائنٹ کا اپنا الگ سیکریٹ ہوتا ہے: پرائمری کے سیکریٹ کو تبدیل کرنا بیک اپ کے سیکریٹ کو تبدیل نہیں کرتا۔

json

// response 200
{
    "detail": {
        "code": 10000,
        "status": "rotated",
        "data": {
            "id": 1,
            "secret": "whsec_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
        }
    }
}

حذف کریں — `DELETE /apiv2/webhooks/{id}`

اینڈ پوائنٹ کو مکمل طور پر حذف کرتا ہے اور اس کا کردار خالی کر دیتا ہے۔ 204 واپس کرتا ہے (کوئی باڈی نہیں)؛ غیر متعلقہ یا غیر موجود id پر 404 ملتا ہے۔

bash

curl -X DELETE https://netts.io/apiv2/webhooks/1 \
  -H "X-API-KEY: your_api_key" -H "X-Real-IP: your_whitelisted_ip"

وہ ویب ہکس جو ہم ڈیلیور کرتے ہیں

جب آپ کے آرڈرز میں سے کوئی ایک مکمل ہو جاتا ہے، تو Netts آپ کے primary اینڈ پوائنٹ پر ایک POST بھیجتا ہے۔ ہر باڈی application/json (UTF-8) ہوتی ہے؛ ایڈریس اور ہیشز ہمیشہ مکمل ویلیوز پر مشتمل ہوتے ہیں۔

تمام واقعات کے لیے مشترکہ فیلڈز:

فیلڈ	قسم	تفصیل
`event`	string	واقعے کی قسم — آپ کے ہینڈلر کے لیے روٹنگ کی (routing key)
`delivery_id`	int	ڈیلیوری ID — آپ کی طرف ڈپلیکیٹ ہٹانے کی کلید (dedup key)۔ `X-Netts-Delivery` ہیڈر میں بھی بھیجی جاتی ہے۔
`order_id`	string	آپ کی آرڈر ID
`order_type`	string	`1h`، `5m`، `bandwidth` یا `activation`
`tx_hashes`	string[]	آپریشن کے تمام ٹرانزیکشن ہیشز، ہر ایک آن چین تصدیق شدہ
`confirmed_at`	string	UTC ISO-8601

`delegation.confirmed` — Energy کرایہ پر لینا

json

{
    "event": "delegation.confirmed",
    "delivery_id": 1,
    "order_id": "1Hxxxxxxxxxx",
    "order_type": "1h",
    "receive_address": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "energy_amount": 65000,
    "tx_hash": "0000000000000000000000000000000000000000000000000000000000000000",
    "tx_hashes": ["0000000000000000000000000000000000000000000000000000000000000000"],
    "delegation_timestamp": 1700000000000,
    "confirmed_at": "2026-01-01T00:00:00Z"
}

فیلڈ	قسم	تفصیل
`order_type`	string	`1h` یا `5m`
`receive_address`	string	TRON ایڈریس جس نے Energy وصول کی
`energy_amount`	int	ڈیلیگیٹ کی گئی Energy کی مقدار
`tx_hash`	string	پرانی فیلڈ (Legacy field)، مطابقت کے لیے برقرار رکھی گئی: بالکل `tx_hashes[0]` جیسی
`delegation_timestamp`	int?	اختیاری — صرف اس وقت موجود ہوتی ہے جب تصدیق Mongo پاتھ کے ذریعے ہوئی ہو

نئے انٹیگریشنز میں tx_hashes کو ترجیح دیں — اصولی طور پر ایک آرڈر ایک سے زیادہ ٹرانزیکشنز کے ذریعے بھی مکمل ہو سکتا ہے۔ tx_hash بدستور کام کرتی رہے گی۔

`bandwidth.delegated` — Bandwidth آرڈر

json

{
    "event": "bandwidth.delegated",
    "delivery_id": 2,
    "order_id": "B1Hxxxxxxxxxxxxx",
    "order_type": "bandwidth",
    "rental_label": "1h",
    "rental_seconds": 3600,
    "receive_address": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "bandwidth_amount": 400,
    "fulfillment": "delegated",
    "tx_hashes": ["0000000000000000000000000000000000000000000000000000000000000000"],
    "confirmed_at": "2026-01-01T00:00:00Z"
}

فیلڈ	قسم	تفصیل
`rental_label` / `rental_seconds`	string / int	کرایہ کی مدت، مثلاً `1h` / `3600`
`receive_address`	string	TRON ایڈریس جس نے Bandwidth وصول کی
`bandwidth_amount`	int	Bandwidth یونٹس (نیٹ)
`fulfillment`	string	آرڈر کس طرح مکمل کیا گیا — نیچے دیکھیں

fulfillment کی ویلیوز:

ویلیو	معنی	`tx_hashes`
`delegated`	ہمارے پول سے Bandwidth ڈیلیگیٹ کی گئی	1+ ہیشز
`trx_send`	ڈیلیگیٹ کرنے کے بجائے ایڈریس پر TRX بھیج کر مکمل کیا گیا	1+ ہیشز
`already_enough`	ایڈریس کے پاس پہلے سے ہی کافی مفت Bandwidth موجود تھی — آن چین کچھ نہیں بھیجا گیا	خالی

already_enough واحد صورت ہے جہاں tx_hashes خالی ہوتی ہے: آرڈر کامیابی کے ساتھ بند ہو جاتا ہے، لیکن کوئی ٹرانزیکشن نہیں ہوتی کیونکہ اس کی ضرورت ہی نہیں تھی۔

`activation.confirmed` — ایڈریس ایکٹیویشن

json

{
    "event": "activation.confirmed",
    "delivery_id": 3,
    "order_id": "123456",
    "order_type": "activation",
    "address": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "activation_type": "ACC_CREATE",
    "source": "telegram_bot",
    "tx_hashes": ["0000000000000000000000000000000000000000000000000000000000000000"],
    "confirmed_at": "2026-01-01T00:00:00Z"
}

فیلڈ	قسم	تفصیل
`order_id`	string	ایکٹیویشن آرڈر ID (عددی سٹرنگ)
`address`	string	فعال کیا گیا TRON ایڈریس
`activation_type`	string	`ACC_CREATE` (AccountCreateContract) یا `DIRECT` (TRX ٹرانسفر)
`source`	string	ماخذ کا نشان۔ یا تو سروس ٹیگ، یا اس Energy آرڈر کی ID جسے ایکٹیویشن کی ضرورت تھی

صرف حقیقی ایکٹیویشنز ہی ڈیلیور کی جاتی ہیں۔ اگر ایڈریس پہلے ہی فعال نکلا اور کوئی ٹرانزیکشن نہیں کی گئی، تو کوئی ویب ہک بالکل نہیں بھیجا جاتا۔

ایسا Energy آرڈر جسے ایکٹیویشن کی بھی ضرورت تھی، وہ دو ویب ہکس بناتا ہے — ایک activation.confirmed اور ایک delegation.confirmed۔ یہ الگ الگ delivery_ids کے ساتھ الگ الگ واقعات ہیں؛ انہیں event فیلڈ کے ذریعے روٹ کریں۔

وہ ہیڈرز جو ہم بھیجتے ہیں:

ہیڈر	ویلیو
`X-Netts-Event`	واقعے کی قسم: `delegation.confirmed`، `bandwidth.delegated` یا `activation.confirmed`
`X-Netts-Delivery`	`delivery_id` (ڈپلیکیٹ چیک کے لیے)
`X-Netts-Timestamp`	بھیجنے کے وقت کا unix سیکنڈ
`X-Netts-Signature`	`sha256=<hex>`، `hex = HMAC_SHA256(secret, "<timestamp>." + raw_body)`
`User-Agent`	`netts-webhook/1.0`

دستخط کی تصدیق کرنا

دستخط Stripe کی اسکیم (timestamp.body) کی پیروی کرتا ہے، جس کا حساب ہمارے بھیجے گئے خام بائٹس (raw bytes) پر لگایا جاتا ہے۔ اپنے secret کے ساتھ اس کا دوبارہ حساب لگائیں، کانسٹنٹ ٹائم (constant-time) میں موازنہ کریں، اور اگر X-Netts-Timestamp کا فرق ±5 منٹ کی حد سے باہر ہو تو مسترد کر دیں (ری پلے پروٹیکشن)۔

اس اینڈ پوائنٹ کے سیکریٹ سے تصدیق کریں جس نے درخواست وصول کی ہے: پرائمری اور بیک اپ کے الگ الگ سیکریٹس ہوتے ہیں۔ اگر آپ کے دونوں ایڈریسز ایک ہی ہینڈلر کے ذریعے ہینڈل کیے جا رہے ہیں، تو اس URL کی بنیاد پر سیکریٹ منتخب کریں جس پر درخواست موصول ہوئی تھی۔

python

import hmac, hashlib, time

def verify(raw_body: bytes, sig_header: str, ts_header: str, secret: str) -> bool:
    # freshness (anti-replay)
    if abs(time.time() - int(ts_header)) > 300:
        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)

# Flask example:
# ok = verify(request.get_data(),
#             request.headers["X-Netts-Signature"],
#             request.headers["X-Netts-Timestamp"], SECRET)

ترسیل کے اصول و طریقہ کار (اہم — کم از کم ایک بار / at-least-once)

ترسیل کم از کم ایک بار (at-least-once) ہوتی ہے: اگر جواب ڈراپ ہو جائے تو دوبارہ کوشش کی جا سکتی ہے، لہذا آپ کو ایک ہی واقعہ دو بار موصول ہو سکتا ہے۔ چونکہ کاروباری کارروائی (USDT جاری کرنا) مالی طور پر حساس ہے:

ڈپلیکیٹ ہٹانا (Dedup) لازمی ہے — ہر واقعے کو delivery_id (اور/یا order_id) کے ذریعے آئڈیمپوٹینٹلی (idempotently) پروسیس کریں؛ بار بار آنے والے کو نظر انداز کریں۔
پیسوں کی کسی بھی کارروائی سے پہلے HMAC کی توثیق کریں — باڈی پر اس وقت تک بھروسہ نہ کریں جب تک دستخط میچ نہ ہو جائے اور X-Netts-Timestamp تازہ نہ ہو۔
2xx جواب صرف اسی وقت دیں جب آپ نے واقعے کو پائیدار طور پر محفوظ کر لیا ہو — بصورت دیگر ہم (درست طور پر) دوبارہ کوشش کریں گے۔

وصولی کی تصدیق کے لیے 2xx واپس کریں؛ کوئی بھی غیر 2xx / ٹائم آؤٹ دوبارہ کوشش کو متحرک کر دیتا ہے۔

کوششوں کی ترتیب:

دوبارہ کوششیں آپ کے primary اینڈ پوائنٹ پر جاتی ہیں۔ مدت آرڈر کی قسم پر منحصر ہے: 5m آرڈرز تقریباً 1 منٹ تک دوبارہ کوشش کرتے ہیں، دیگر تمام اقسام تقریباً 10 منٹ تک۔
اگر وہ وقت ختم ہو جائے اور آپ نے backup رجسٹر کیا ہو، تو ترسیل وہاں منتقل ہو جاتی ہے اور دوبارہ کوشش کا شیڈول نئے سرے سے شروع ہوتا ہے — بیک اپ کے اپنے سیکریٹ کے ساتھ دستخط شدہ۔
صرف اس وقت جب بیک اپ کا وقت بھی ختم ہو جائے، ترسیل کو ناکام (dead) قرار دیا جاتا ہے۔

پورے عمل میں ایک ہی delivery_id استعمال ہوتی ہے، لہذا وہ پیغام جو پہلے پرائمری پر ناکام ہوا اور پھر بیک اپ پر کامیاب رہا، آپ کے ڈپلیکیٹ چیک کے عمل کے لیے اب بھی ایک ہی واقعہ ہے۔

غلطی کوڈ کا حوالہ (Error Code Reference)

کوڈ	تفصیل	HTTP اسٹیٹس
`10000`	کامیابی (created / ok / updated / rotated)	200 / 201
`-`	حذف کر دیا گیا (کوئی باڈی نہیں)	204
`4000`	غلط / غیر محفوظ ویب ہک URL (https نہیں ہے، پرائیویٹ/لوپ بیک، اسناد شامل ہیں، بہت طویل ہے)	400
`-1`	غلط API کلید / IP وائٹ لسٹ میں نہیں ہے	401
`-1`	اینڈ پوائنٹ نہیں ملا (یا آپ کا نہیں ہے)	404
`4090`	اینڈ پوائنٹ کی حد پوری ہو گئی (زیادہ سے زیادہ 2: primary، backup)	409
`4091`	مطلوبہ کردار پہلے سے تفویض شدہ ہے — `PATCH` کے ساتھ تبدیل کریں یا پہلے سے موجود اینڈ پوائنٹ کو حذف کریں	409
`4220`	اپ ڈیٹ کرنے کے لیے کچھ نہیں ہے (خالی باڈی کے ساتھ PATCH)	422
`5003`	اینڈ پوائنٹ بنانے میں ناکامی (دوبارہ کوشش کریں)	503

شرح کی حدود (Rate Limits)

فی API کلید محدود ہے (ہیڈر X-API-KEY):

مدت	حد
1 سیکنڈ	5 درخواستیں
1 منٹ	150 درخواستیں

شرح کی حد سے تجاوز (429)

json

{ "message": "API rate limit exceeded" }

نوٹس

سیکریٹ صرف ایک بار دکھایا جاتا ہے — بناتے وقت اور گھوماتے (rotate) وقت۔ یہ GET/LIST سے کبھی واپس نہیں ہوتا۔ کھو گیا؟ نیا حاصل کرنے کے لیے rotate کریں۔
دو اینڈ پوائنٹس، کوئی فین آؤٹ نہیں: ایک primary اور ایک backup۔ ہر تصدیق شدہ آرڈر ایک ویب ہک تیار کرتا ہے، جو پرائمری کو ڈیلیور کیا جاتا ہے؛ بیک اپ صرف اس وقت استعمال ہوتا ہے جب پرائمری کی کوششیں ختم ہو جائیں۔
بغیر کسی رکاوٹ کے URL کی تبدیلی (Zero-downtime): نیا ایڈریس backup کے طور پر رجسٹر کریں، اس کی تصدیق کریں، پھر اسے PATCH کے ذریعے primary میں تبدیل کر دیں — یہ تبدیلی فوری اور بیک وقت (atomic) ہوتی ہے۔
روکنا: PATCH … {"is_active": false} اینڈ پوائنٹ کو ضائع کیے بغیر ترسیل کو روک دیتا ہے۔
صرف کامیابی کے واقعات: delegation.confirmed، bandwidth.delegated، activation.confirmed۔ ناکامی کا کوئی واقعہ نہیں ہوتا — ناکام یا ٹائم آؤٹ آرڈر پر کوئی ویب ہک نہیں بنتا۔
وقت کے ساتھ ساتھ واقعات کی نئی اقسام شامل کی جا سکتی ہیں۔ event فیلڈ کے ذریعے روٹ کریں اور ان اقسام کو نظر انداز کر دیں جنہیں آپ فی الحال ہینڈل نہیں کرتے — انہیں وصول کرنا شروع کرنے کے لیے آپ کو کبھی بھی کچھ نیا رجسٹر کرنے کی ضرورت نہیں ہوگی۔
ترسیل سے پہلے ہیشز کی آن چین تصدیق کی جاتی ہے (اوپر دیا گیا نوٹ دیکھیں): ایک ویب ہک میں یا تو وہ تمام ہیشز شامل ہوتے ہیں جو کسی بلاک میں موجود ہیں، یا پھر وہ سرے سے بھیجا ہی نہیں جاتا۔
رجسٹریشن کے وقت اور ہر ترمیم پر SSRF کی حفاظت کے لیے URLs کی تصدیق کی جاتی ہے؛ ترسیل کا نظام بھیجتے وقت دوبارہ تصدیق کرتا ہے۔

ویب ہکس — آرڈر کی اطلاعات ​

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

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

بنیادی اور بیک اپ اینڈ پوائنٹ ​

اینڈ پوائنٹس کا انتظام کریں ​

بنائیں — POST /apiv2/webhooks ​

فہرست — GET /apiv2/webhooks ​

ایک حاصل کریں — GET /apiv2/webhooks/{id} ​

ترمیم کریں — PATCH /apiv2/webhooks/{id} ​

سیکریٹ تبدیل کریں (Rotate secret) — POST /apiv2/webhooks/{id}/rotate-secret ​

حذف کریں — DELETE /apiv2/webhooks/{id} ​

وہ ویب ہکس جو ہم ڈیلیور کرتے ہیں ​

delegation.confirmed — Energy کرایہ پر لینا ​

bandwidth.delegated — Bandwidth آرڈر ​

activation.confirmed — ایڈریس ایکٹیویشن ​

دستخط کی تصدیق کرنا ​

ترسیل کے اصول و طریقہ کار (اہم — کم از کم ایک بار / at-least-once) ​

غلطی کوڈ کا حوالہ (Error Code Reference) ​

شرح کی حدود (Rate Limits) ​

شرح کی حد سے تجاوز (429) ​

نوٹس ​

ویب ہکس — آرڈر کی اطلاعات

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

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

بنیادی اور بیک اپ اینڈ پوائنٹ

اینڈ پوائنٹس کا انتظام کریں

بنائیں — `POST /apiv2/webhooks`

فہرست — `GET /apiv2/webhooks`

ایک حاصل کریں — `GET /apiv2/webhooks/{id}`

ترمیم کریں — `PATCH /apiv2/webhooks/{id}`

سیکریٹ تبدیل کریں (Rotate secret) — `POST /apiv2/webhooks/{id}/rotate-secret`

حذف کریں — `DELETE /apiv2/webhooks/{id}`

وہ ویب ہکس جو ہم ڈیلیور کرتے ہیں

`delegation.confirmed` — Energy کرایہ پر لینا

`bandwidth.delegated` — Bandwidth آرڈر

`activation.confirmed` — ایڈریس ایکٹیویشن

دستخط کی تصدیق کرنا

ترسیل کے اصول و طریقہ کار (اہم — کم از کم ایک بار / at-least-once)

غلطی کوڈ کا حوالہ (Error Code Reference)

شرح کی حدود (Rate Limits)

شرح کی حد سے تجاوز (429)

نوٹس