Open in
ویب ہک اینڈ پوائنٹس
ہر اینڈ پوائنٹ کے لیے الگ سیکرٹس اور ایونٹ فلٹرز کے ساتھ متعدد ویب ہک URLs کا انتظام کریں۔
اینڈپوائنٹ پر مبنی webhook سسٹم آپ کو ہر تنظیم کے لیے متعدد منزلیں رجسٹر کرنے دیتا ہے، جن میں سے ہر ایک کا اپنا secret، اپنی status، اور event types کے ایک ذیلی مجموعے کے لیے اپنی subscription ہوتی ہے۔ یہ تمام نئی integrations کے لیے تجویز کردہ ماڈل ہے۔
اس کا موازنہ legacy single-URL webhook سے کریں، جسے backward compatibility کے لیے برقرار رکھا گیا ہے، مگر یہ ہر تنظیم کے لیے صرف ایک URL کی معاونت کرتا ہے۔
اینڈپوائنٹس
| طریقہ | پاتھ | مطلوبہ کردار | تفصیل |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | اینڈ پوائنٹس کی فہرست |
POST | /v1/developer/webhook-endpoints | admin+ | ایک اینڈ پوائنٹ بنائیں |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | لیبل، URL، ایونٹس یا اسٹیٹس اپ ڈیٹ کریں |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | ایک اینڈ پوائنٹ حذف کریں |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | سائننگ سیکرٹ تبدیل کریں |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | ایک دستخط شدہ ٹیسٹ ڈیلیوری بھیجیں |
GET | /v1/developer/webhook-deliveries | admin+ | حالیہ اینڈ پوائنٹ اور لیگیسی ڈیلیوری کے نتائج کا جائزہ لیں |
اینڈ پوائنٹ آبجیکٹ
{
"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",
"paused_at": null,
"pause_last_error": "",
"pause_undelivered_count": null,
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z"
}| فیلڈ | قسم | وضاحت |
|---|---|---|
id | UUID | اینڈ پوائنٹ شناخت |
label | اسٹرنگ | ڈسپلے نام، 1–120 حروف |
url | اسٹرنگ | HTTPS URL؛ ترقیاتی ماحول کے لیے http://localhost کی اجازت ہے |
events | اسٹرنگ کی اَرے | سبسکرائب کیے گئے ایونٹ کی اقسام (درست قدریں دیکھیں)۔ خالی اَرے واضح طور پر مخصوص ایونٹس (telephony.turn / web.turn / call.status_changed) کے علاوہ تمام ایونٹس کو سبسکرائب کرتی ہے |
status | اسٹرنگ | active، disabled (دستی طور پر موقوف)، یا failing (جب کوئی ترسیل ایک بھی 2xx کے بغیر اپنی 24 گھنٹے کی دوبارہ کوششوں کا نظام الاوقات مکمل کر لے تو خودکار طور پر مقرر ہوتا ہے) |
agent_id | انٹیجر | null | وہ ایجنٹ جس تک یہ اینڈ پوائنٹ محدود ہے؛ null سے مراد پوری تنظیم ہے |
agent_name | اسٹرنگ | null | محدود ایجنٹ کا نام، یا پوری تنظیم کے اینڈ پوائنٹ کے لیے null |
secret_hint | اسٹرنگ | دستخطی راز کے پہلے 4 اور آخری 4 حروف، بیضوی نشان (a1b2…9f0e) کے ساتھ — مکمل قدر ظاہر کیے بغیر مقامی طور پر محفوظ کیے گئے راز سے ملان کرنے کے لیے کافی |
paused_at | ٹائم اسٹیمپ | null | جب ThunderPhone نے اینڈ پوائنٹ کو failing پر مقرر کیا۔ جب یہ active یا disabled ہو تو null |
pause_last_error | اسٹرنگ | اینڈ پوائنٹ موقوف کیے جانے پر ترسیل کی آخری خرابی، مثلاً HTTP 503: Service Unavailable۔ failing کے علاوہ خالی |
pause_undelivered_count | انٹیجر | null | اینڈ پوائنٹ کی آخری کامیاب ترسیل کے بعد سے نہ پہنچائے گئے ایونٹس، جنہیں موقوف کیے جانے پر گنا جاتا ہے |
created_at, updated_at | ٹائم اسٹیمپ |
درست ایونٹ اقسام
events کو اسی درست سیٹ کے خلاف ویلیڈیٹ کیا جاتا ہے — فہرست سے باہر کی قدریں
400 واپس کرتی ہیں۔ ہر قسم کی پے لوڈ ساخت کے لیے ایونٹس کی فہرست
دیکھیں۔
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(محفوظ؛ ابھی تک جاری نہیں کیا گیا)scheduled.skipped,scheduled.failedcall.graded,call.data_extracted,call.transfer_completed,call.status_changedcampaign.completedissue.reported,issue.escalatedtest-call.completedalert.triggeredphone_number.spam_risk_changed
issue.escalated اور phone_number.spam_risk_changed میں ایجنٹ کا کوئی سیاق موجود نہیں ہوتا اور
انہیں صرف تنظیم بھر کے اینڈ پوائنٹس پر بھیجا جاتا ہے۔
voice.ready اور voice.failed کو واضح طور پر منتخب نہیں کیا جا سکتا۔ انہیں وصول کرنے کے لیے
events: [] کے ساتھ تنظیم بھر کے لیے ایک اینڈپوائنٹ بنائیں۔ خالی ایونٹ
فہرست telephony.turn، web.turn اور call.status_changed کے علاوہ ہر معاونت یافتہ ایونٹ وصول کرتی ہے، جنہیں واضح طور پر منتخب کرنا ضروری ہے۔
اینڈ پوائنٹ اسٹیٹسز
active— ڈیلیوریز معمول کے مطابق جاری رہتی ہیں۔disabled—PATCHکے ذریعے دستی طور پر روکا گیا۔ کوئی درخواست نہیں بھیجی جاتی۔ ہم کبھی بھیdisabledاینڈپوائنٹ کی حالت تبدیل نہیں کرتے؛ اسے دوبارہactiveکرنا ہمیشہ آپ کا فیصلہ ہوتا ہے۔failing— جب اینڈپوائنٹ کو ڈیلیوری اپنی مکمل دوبارہ کوشش کی شیڈول (24 گھنٹوں میں 8 کوششیں) استعمال کر لے اور کبھی بھی 2xx حاصل نہ کرے تو یہ خودکار طور پر سیٹ ہو جاتا ہے۔ ناکام اینڈپوائنٹ کو مزید ٹریفک موصول نہیں ہوتی۔ ایسا ہونے پر ہم آپ کی تنظیم کے مالکان اور ایڈمنز کو ای میل کرتے ہیں، اور ڈیش بورڈ رکے ہوئے اینڈپوائنٹ کو دوبارہ فعال کریں بٹن کے ساتھ دکھاتا ہے۔ اینڈپوائنٹ درست ہو جانے کے بعد،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"]درخواست کے فیلڈز
| فیلڈ | قسم | ضروری | تفصیل |
|---|---|---|---|
label | string | ہاں | 1–120 حروف |
url | string | ہاں | HTTPS URL (http صرف localhost / 127.0.0.1 کے لیے اجازت یافتہ ہے) |
events | array | نہیں | خالی/چھوڑنے پر telephony.turn / web.turn / call.status_changed کے علاوہ تمام ایونٹس سبسکرائب ہوتے ہیں، جن کے لیے واضح سبسکرپشن درکار ہے۔ درست ایونٹ اقسام میں درج اقدار استعمال کریں؛ نقلیں ہٹا دی جاتی ہیں |
agent_id | integer | null | نہیں | اس تنظیم میں کسی ایجنٹ تک ڈیلیوری محدود کریں؛ تنظیم بھر کے اینڈپوائنٹ کے لیے اسے چھوڑ دیں یا null استعمال کریں |
اینڈ پوائنٹ آبجیکٹ کے ساتھ 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"]
}'| فیلڈ | قسم | وضاحت |
|---|---|---|
label | اسٹرنگ | |
url | اسٹرنگ | |
events | اَرے | |
status | اسٹرنگ | active یا disabled۔ سرور کی جانب سے failing نشان زدہ اینڈ پوائنٹ کو دوبارہ فعال کرنے کے لیے active مقرر کریں |
agent_id | انٹیجر | null | اینڈ پوائنٹ کو محدود کرنے کے لیے ایجنٹ id مقرر کریں، یا اسے تنظیم بھر کے لیے null کریں |
اپ ڈیٹ شدہ اینڈ پوائنٹ آبجیکٹ کے ساتھ 200 OK واپس کرتا ہے۔
سائننگ سیکرٹ کو روٹیٹ کریں
کسی اینڈ پوائنٹ کا سائننگ سیکرٹ تبدیل کریں، مثلاً جب وہ گم ہو گیا ہو یا لیک ہونے کا امکان ہو۔ آپ ڈیش بورڈ بھی استعمال کر سکتے ہیں: اینڈ پوائنٹ کو انٹیگریشنز → ویب ہکس کے تحت کھولیں (تنظیم بھر کے اور ایجنٹ اینڈ پوائنٹس دونوں وہاں درج ہوتے ہیں) اور تبدیل کریں منتخب کریں۔
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'| فیلڈ | قسم | ضروری | وضاحت |
|---|---|---|---|
include_copies | بولین | نہیں | ڈیفالٹ true ہے۔ آپ کی تنظیم کے ان دیگر اینڈپوائنٹس کو بھی نیا سیکرٹ دیتا ہے جن کا URL اور موجودہ سیکرٹ ایک جیسا ہو، مثلاً دوسرے ایجنٹس پر اس اینڈپوائنٹ کی نقول، تاکہ ایک وصول کنندہ ایک ہی سیکرٹ سے تصدیق کرتا رہے |
200 OK واپس کرتا ہے:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| فیلڈ | قسم | وضاحت |
|---|---|---|
endpoint | آبجیکٹ | اپنے نئے secret_hint کے ساتھ اینڈپوائنٹ آبجیکٹ |
secret | اسٹرنگ | نیا سائننگ سیکرٹ۔ صرف اسی جواب میں واپس کیا جاتا ہے |
rotated_endpoint_ids | UUID کی فہرست | ہر وہ اینڈپوائنٹ جو اب نیا سیکرٹ استعمال کرتا ہے |
آزمائشی ڈیلیوری بھیجیں
معیاری ڈیلیوری پائپ لائن استعمال کرتے ہوئے ایک اینڈپوائنٹ کو مصنوعی webhook.test ایونٹ بھیجیں، جس میں معیاری JSON سیریلائزیشن، دونوں دستخطی ہیڈرز، ڈیلیوری ریکارڈنگ، اور دوبارہ کوششوں کا حساب شامل ہو۔
ٹیسٹ اپنے 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 سبسکرپشن میں شامل نہیں کیا جا سکتا۔
اگر پہلی کوشش ناکام ہو جائے تو ThunderPhone تقریباً ایک منٹ بعد ایک بار دوبارہ کوشش کرتا ہے اور پھر رک جاتا ہے؛ اس کے بعد ڈیلیوری ڈیلیوریز ڈیبگ کریں کے تحت status: "failed" دکھاتی ہے۔
آزمائشی ڈیلیوری کبھی بھی اینڈ پوائنٹ کو failing نشان زد نہیں کرتی۔
حقیقی ایونٹ کی ساخت کے خلاف ٹرگر ترتیب دینے کے لیے، اختیاری 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 رویہ برقرار رہتا ہے۔
کال مکمل (telephony.complete, web.complete) اور call.data_extracted
نمونے، اصل کالز کی طرح، ایجنٹ کے اپنے جمع کیے جانے والے ڈیٹا کے فیلڈز کو
placeholder قدروں کے ساتھ extracted_data.fields کے تحت رکھتے ہیں۔ ایسے
ایجنٹ کے لیے جو کوئی ڈیٹا جمع نہیں کرتا، کال مکمل نمونہ اصل کالز کی طرح
extracted_data: null بھیجتا ہے، اور call.data_extracted نمونے میں fields
خالی ہوتے ہیں (اصل کالز ایسے ایجنٹ کے لیے کبھی یہ ایونٹ نہیں بھیجتیں)۔
جب ایجنٹ کی کال خلاصہ بندی بند ہو تو نمونے کا summary null ہوتا ہے۔ ایجنٹ
کے endpoint پر نمونہ اسی ایجنٹ کے مطابق ہوتا ہے؛ تنظیم بھر کے endpoint پر،
اسے کسی ایک ایجنٹ کے مطابق بنانے کے لیے اختیاری agent_id دیں، یا عمومی
نمونے کے لیے اسے چھوڑ دیں۔
ایک اینڈ پوائنٹ حذف کریں
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 دیکھیں۔
یہ دونوں ویب ہک سسٹمز کی حالیہ کوششیں دکھاتا ہے، جن میں کال ID، URL ماخذ، HTTP اسٹیٹس، کوششوں کی تعداد، اجازت یافتہ ناکامی کی قسم، اور اگلی دوبارہ کوشش کا وقت شامل ہے۔
یہ کبھی بھی ایونٹ پے لوڈ، ٹرانسکرپٹ، ذخیرہ شدہ خرابی کا متن، جوابی باڈی، یا URL راستہ واپس نہیں کرتا۔
آپ یہی حالیہ ہسٹری ایجنٹس → ایک ایجنٹ منتخب کریں → ویب ہکس → حالیہ ڈیلیوریز میں بھی دیکھ سکتے ہیں۔ قطاریں اینڈ پوائنٹ کا لیبل اور تازہ ترین کوشش میں استعمال ہونے والا URL ماخذ دکھاتی ہیں۔ یہ ناقابلِ تبدیلی آڈٹ لاگ کے بجائے عملی حالت ہے: کسی اینڈ پوائنٹ کو حذف کرنے سے اس کی ڈیلیوری قطاریں بھی حذف ہو جاتی ہیں۔
n8n کے 404 کے لیے، پہلے تصدیق کریں کہ ورک فلو فعال ہے، POST قبول کرتا ہے، اور
ٹیسٹ URL کے بجائے پروڈکشن ویب ہک URL استعمال کرتا ہے۔ 401 یا 403 توثیق یا
دستخط کی توثیق کی طرف اشارہ کرتا ہے؛ ٹائم آؤٹس منزل کی تاخیر
یا دستیابی کی طرف اشارہ کرتے ہیں؛ TLS کی خرابیاں سرٹیفکیٹ چین، ہوسٹ نیم، یا میعاد ختم ہونے کی طرف اشارہ کرتی ہیں۔