ویب ہُک اینڈ پوائنٹس

اینڈپوائنٹ پر مبنی webhook نظام آپ کو ہر تنظیم کے لیے متعدد منزلیں رجسٹر کرنے دیتا ہے، جن میں سے ہر ایک کا اپنا secret، اپنی status، اور event اقسام کے ایک ذیلی مجموعے کی اپنی subscription ہوتی ہے۔ تمام نئی integrations کے لیے یہی تجویز کردہ ماڈل ہے۔

اس کا موازنہ پرانے واحد-URL webhook سے کریں، جسے backward compatibility کے لیے برقرار رکھا گیا ہے، مگر یہ ہر تنظیم کے لیے صرف ایک URL کی معاونت کرتا ہے۔

اینڈپوائنٹس

اینڈپوائنٹ آبجیکٹ

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

درست event اقسام

events کو اسی عین سیٹ کے خلاف validate کیا جاتا ہے — فہرست سے باہر کی اقدار 400 واپس کرتی ہیں۔ ہر قسم کی payload ساخت کے لیے Events catalog دیکھیں۔

• telephony.incoming, telephony.complete, telephony.tool
• web.incoming, web.complete, web.tool
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

اینڈپوائنٹ statuses

• active — ڈیلیوریز معمول کے مطابق جاری رہتی ہیں۔
• disabled — PATCH کے ذریعے دستی طور پر روکا گیا۔ کوئی request نہیں بھیجی جاتی۔ ہم کبھی بھی disabled اینڈپوائنٹ کی status تبدیل نہیں کرتے؛ اسے دوبارہ active کرنا ہمیشہ آپ کا فیصلہ ہے۔
• failing — جب اینڈپوائنٹ کو کوئی ڈیلیوری ایک بھی 2xx حاصل کیے بغیر اپنے پورے retry شیڈول (24 گھنٹوں میں 8 کوششیں) سے گزر جائے تو خودکار طور پر سیٹ ہوتا ہے۔ failing اینڈپوائنٹ کو مزید کوئی traffic موصول نہیں ہوتا۔ اینڈپوائنٹ درست ہو جانے پر، اس کی status کو PATCH کے ذریعے دوبارہ active کریں؛ جن ڈیلیوریز کا retry شیڈول ابھی ختم نہیں ہوا وہ اسی مقام سے دوبارہ جاری ہو جاتی ہیں جہاں وہ رکی تھیں۔

اینڈپوائنٹس کی فہرست

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

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

ایک اینڈپوائنٹ بنائیں

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

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

اینڈپوائنٹ آبجیکٹ کے ساتھ 201 Created واپس کرتا ہے، نیز ایک اضافی اعلیٰ سطحی secret فیلڈ بھی واپس کرتا ہے جس میں خام سائننگ کلید ہوتی ہے — ایک 48-حروف کی hex اسٹرنگ:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

ایک اینڈپوائنٹ اپ ڈیٹ کریں

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

اپ ڈیٹ شدہ اینڈپوائنٹ آبجیکٹ کے ساتھ 200 OK واپس کرتا ہے۔

آزمائشی ترسیل بھیجیں

معمول کی ترسیل پائپ لائن استعمال کرتے ہوئے ایک اینڈپوائنٹ کو مصنوعی webhook.test ایونٹ بھیجیں، جس میں معیاری JSON سیریلائزیشن، X-ThunderPhone-Signature، ترسیل ریکارڈنگ، اور دوبارہ کوشش کا ریکارڈ شامل ہے۔ یہ ٹیسٹ منتخب اینڈپوائنٹ کو اس کے events فلٹر سے قطع نظر ہدف بناتا ہے۔

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

اینڈپوائنٹ کو اس طرح کا لفافہ موصول ہوتا ہے:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

پہلی کوشش کے بعد API 200 OK واپس کرتا ہے، خواہ منزل سے خرابی واپس آئے۔ ترسیل کے نتیجے کے لیے success، status، response_code، اور error دیکھیں:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test مصنوعی ہے اور اسے کسی اینڈپوائنٹ کی events سبسکرپشن میں شامل نہیں کیا جا سکتا۔ اگر پہلی کوشش ناکام ہو جائے تو ترسیل معمول کے ایونٹ ترسیلات جیسا ہی دوبارہ کوشش کا شیڈول اختیار کرتی ہے۔

اینڈ پوائنٹ حذف کریں

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content واپس کرتا ہے۔ URL پر ڈیلیوری فوراً رک جاتی ہے؛ جاری دوبارہ کوششیں ترک کر دی جاتی ہیں۔

متعلقہ