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

ہر اینڈ پوائنٹ کے لیے الگ رازوں اور ایونٹ فلٹرز کے ساتھ متعدد ویب ہُک URLs کا انتظام کریں۔

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

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

اینڈ پوائنٹس#

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

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

درست ایونٹ کی اقسام#

events کو بالکل اس سیٹ کے خلاف جانچا جاتا ہے — فہرست سے باہر کی اقدار 400 واپس کرتی ہیں۔ ہر قسم کے پےلوڈ کی ساخت کے لیے ایونٹس کی فہرست دیکھیں۔

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

issue.escalated میں ایجنٹ کا کوئی سیاق نہیں ہوتا اور یہ صرف تنظیم بھر کے اینڈ پوائنٹس کو پہنچایا جاتا ہے۔

voice.ready اور voice.failed کو صراحتاً منتخب نہیں کیا جا سکتا۔ انہیں وصول کرنے کے لیے events: [] کے ساتھ تنظیم بھر کا اینڈ پوائنٹ بنائیں۔ خالی ایونٹ فہرست telephony.turn اور web.turn کے علاوہ ہر معاونت یافتہ ایونٹ وصول کرتی ہے، جنہیں صراحتاً منتخب کرنا ضروری ہے۔

اینڈ پوائنٹ کی حالتیں#

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

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

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

اینڈ پوائنٹ آبجیکٹس کی array واپس کرتا ہے۔ صرف اس ایجنٹ تک محدود اینڈ پوائنٹس واپس کرنے کے لیے ?agent_id=42 دیں۔

ایجنٹ تک محدود اینڈ پوائنٹس#

تنظیم بھر کے اینڈ پوائنٹس ہر مطابقت رکھنے والا ایونٹ وصول کرتے ہیں۔ agent_id والا اینڈ پوائنٹ صرف اس ایجنٹ کے سنبھالے گئے کالز کے لیے مطابقت رکھنے والے ایونٹس وصول کرتا ہے؛ جن ایونٹس میں ایجنٹ کا سیاق نہیں ہوتا، جیسے alert.triggered، وہ کبھی اس تک نہیں پہنچتے۔ آپ ایجنٹ بلڈر کے ویب ہکس سیکشن سے بھی یہ اینڈ پوائنٹس بنا اور منظم کر سکتے ہیں۔

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

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 حروف کی ہیکس سٹرنگ:

{
  "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 واپس کرتا ہے۔

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

معیاری JSON سیریلائزیشن، X-ThunderPhone-Signature، ترسیل کی ریکارڈنگ، اور دوبارہ کوشش کے ریکارڈ سمیت، عام ترسیلی پائپ لائن کے ذریعے ایک اینڈ پوائنٹ کو مصنوعی webhook.test ایونٹ بھیجیں۔ یہ ٹیسٹ منتخب کردہ اینڈ پوائنٹ کو اس کے 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 سبسکرپشن میں شامل نہیں کیا جا سکتا۔ اگر پہلی کوشش ناکام ہو جائے تو ترسیل عام ایونٹ ترسیلات جیسا ہی دوبارہ کوشش کا شیڈول اختیار کرتی ہے۔

حقیقی ایونٹ کی ساخت کے مطابق ٹرگر ترتیب دینے کے لیے ایک اختیاری event_type پاس کریں۔ ترسیل پھر بھی مصنوعی ہوتی ہے اور اس میں "sample": true شامل ہوتا ہے؛ کال سے متعلق نمونے call_id: 0 اور agent_id: 0 استعمال کرتے ہیں۔

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type، درست ایونٹ اقسام میں سے کوئی بھی قدر قبول کرتا ہے۔ اسے حذف کرنے سے عمومی webhook.test رویہ برقرار رہتا ہے۔

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

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

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

ترسیلات کی ڈیبگنگ کریں#

یہ نتیجہ اخذ کرنے سے پہلے کہ کوئی ویب ہک نہیں بھیجا گیا، GET /v1/developer/webhook-deliveries کا جائزہ لیں۔ یہ دونوں ویب ہک سسٹمز کی حالیہ کوششیں دکھاتا ہے، جن میں کال آئی ڈی، URL اصل، HTTP اسٹیٹس، کوششوں کی تعداد، اجازت شدہ ناکامی کا زمرہ، اور اگلی دوبارہ کوشش کا وقت شامل ہیں۔ یہ کبھی بھی ایونٹ پے لوڈ، ٹرانسکرپٹ، محفوظ شدہ خرابی کا متن، رسپانس باڈی، یا URL پاتھ واپس نہیں کرتا۔

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

n8n کے 404 کے لیے، پہلے تصدیق کریں کہ ورک فلو فعال ہے، POST قبول کرتا ہے، اور ٹیسٹ URL کے بجائے پروڈکشن ویب ہک URL استعمال کرتا ہے۔ 401 یا 403 تصدیق یا دستخط کی توثیق کی طرف اشارہ کرتا ہے؛ ٹائم آؤٹس منزل کی تاخیر یا دستیابی کی طرف اشارہ کرتے ہیں؛ TLS کی خرابیاں سرٹیفکیٹ چین، ہوسٹ نیم، یا میعاد ختم ہونے کی طرف اشارہ کرتی ہیں۔

متعلقہ#