ThunderPhone v3 اب لائیو ہے۔سیلف سرو، قیمت 2¢ فی منٹ سے شروع۔اعلان پڑھیں

Webhooks

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

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

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

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

اینڈپوائنٹس

طریقہپاتھمطلوبہ کردارتفصیل
GET/v1/developer/webhook-endpointsadmin+اینڈ پوائنٹس کی فہرست
POST/v1/developer/webhook-endpointsadmin+ایک اینڈ پوائنٹ بنائیں
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-secretadmin+سائننگ سیکرٹ تبدیل کریں
POST/v1/developer/webhook-endpoints/{endpoint_id}/testadmin+ایک دستخط شدہ ٹیسٹ ڈیلیوری بھیجیں
GET/v1/developer/webhook-deliveriesadmin+حالیہ اینڈ پوائنٹ اور لیگیسی ڈیلیوری کے نتائج کا جائزہ لیں

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

{
  "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"
}
فیلڈقسموضاحت
idUUIDاینڈ پوائنٹ شناخت
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.turn
  • web.incoming, web.complete, web.tool, web.turn
  • sms.sent, sms.failed
  • sms.received (محفوظ؛ ابھی تک جاری نہیں کیا گیا)
  • scheduled.skipped, scheduled.failed
  • call.graded, call.data_extracted, call.transfer_completed, call.status_changed
  • campaign.completed
  • issue.reported, issue.escalated
  • test-call.completed
  • alert.triggered
  • phone_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
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
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"]
  }'
Python
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"]

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

فیلڈقسمضروریتفصیل
labelstringہاں1–120 حروف
urlstringہاںHTTPS URL (http صرف localhost / 127.0.0.1 کے لیے اجازت یافتہ ہے)
eventsarrayنہیںخالی/چھوڑنے پر telephony.turn / web.turn / call.status_changed کے علاوہ تمام ایونٹس سبسکرائب ہوتے ہیں، جن کے لیے واضح سبسکرپشن درکار ہے۔ درست ایونٹ اقسام میں درج اقدار استعمال کریں؛ نقلیں ہٹا دی جاتی ہیں
agent_idinteger | 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
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
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_idsUUID کی فہرستہر وہ اینڈپوائنٹ جو اب نیا سیکرٹ استعمال کرتا ہے

آزمائشی ڈیلیوری بھیجیں

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

cURL
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
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 کی خرابیاں سرٹیفکیٹ چین، ہوسٹ نیم، یا میعاد ختم ہونے کی طرف اشارہ کرتی ہیں۔


متعلقہ