Open in
Webhook এন্ডপয়েন্ট
প্রতিটি এন্ডপয়েন্টের জন্য আলাদা সিক্রেট ও ইভেন্ট ফিল্টারসহ একাধিক webhook URL পরিচালনা করুন।
এন্ডপয়েন্ট-ভিত্তিক webhook সিস্টেমটি আপনাকে প্রতি organization-এ একাধিক গন্তব্য নিবন্ধন করতে দেয়, প্রতিটির নিজস্ব secret, নিজস্ব status এবং event type-এর একটি উপসেটের জন্য নিজস্ব subscription থাকে। সব নতুন integration-এর জন্য এটিই প্রস্তাবিত মডেল।
লিগ্যাসি একক-URL webhook-এর সঙ্গে তুলনা করুন, যেটি backward compatibility-এর জন্য রাখা হয়েছে, তবে প্রতি org-এ শুধু একটি 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 | এন্ডপয়েন্ট id |
label | string | প্রদর্শন নাম, 1–120 অক্ষর |
url | string | HTTPS URL; ডেভেলপমেন্টের জন্য http://localhost অনুমোদিত |
events | string-এর অ্যারে | সাবস্ক্রাইব করা ইভেন্টের ধরন (বৈধ মান দেখুন)। খালি অ্যারে স্পষ্টভাবে-শুধু ইভেন্টগুলো (telephony.turn / web.turn / call.status_changed) ছাড়া সব ইভেন্টে সাবস্ক্রাইব করে |
status | string | active, disabled (ম্যানুয়ালি বিরত), অথবা failing (কোনো একটিও 2xx ছাড়া ডেলিভারি তার 24 h পুনঃচেষ্টা সূচি শেষ করলে স্বয়ংক্রিয়ভাবে সেট হয়) |
agent_id | integer | null | এই এন্ডপয়েন্ট যে এজেন্টের জন্য নির্ধারিত; null মানে সংস্থাজুড়ে |
agent_name | string | null | নির্ধারিত এজেন্টের নাম, অথবা সংস্থাজুড়ে এন্ডপয়েন্টের জন্য null |
secret_hint | string | এলিপসিসসহ সাইনিং সিক্রেটের প্রথম 4 এবং শেষ 4 অক্ষর (a1b2…9f0e) — সম্পূর্ণ মান প্রকাশ না করে স্থানীয়ভাবে সংরক্ষণ করা সিক্রেটের সঙ্গে মিলিয়ে দেখার জন্য যথেষ্ট |
paused_at | timestamp | null | ThunderPhone কখন এন্ডপয়েন্টকে failing হিসেবে সেট করেছে। এটি active বা disabled থাকলে null |
pause_last_error | string | এন্ডপয়েন্ট বিরত থাকার সময়কার সর্বশেষ ডেলিভারি ত্রুটি, যেমন HTTP 503: Service Unavailable। failing না হলে খালি |
pause_undelivered_count | integer | null | এন্ডপয়েন্ট বিরত হওয়ার সময় গণনা করা, তার সর্বশেষ সফল ডেলিভারির পর থেকে ডেলিভারিবিহীন ইভেন্ট |
created_at, updated_at | timestamp |
বৈধ ইভেন্টের ধরন
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"এন্ডপয়েন্ট অবজেক্ট-এর একটি অ্যারে ফেরত দেয়।
শুধু সেই এজেন্টের জন্য সীমাবদ্ধ এন্ডপয়েন্ট ফেরত পেতে ?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 | স্ট্রিং | হ্যাঁ | 1–120 অক্ষর |
url | স্ট্রিং | হ্যাঁ | HTTPS URL (http শুধুমাত্র localhost / 127.0.0.1-এর জন্য অনুমোদিত) |
events | অ্যারে | না | খালি/বাদ দিলে telephony.turn / web.turn / call.status_changed ছাড়া সব ইভেন্টে সাবস্ক্রাইব করা হয়; এগুলোর জন্য স্পষ্ট সাবস্ক্রিপশন প্রয়োজন। বৈধ ইভেন্টের ধরন-এ তালিকাভুক্ত মানগুলো ব্যবহার করতে হবে; ডুপ্লিকেট সরিয়ে দেওয়া হয় |
agent_id | পূর্ণসংখ্যা | null | না | এই সংস্থার একটি এজেন্টের জন্য ডেলিভারির পরিধি নির্ধারণ করুন; সংস্থা-ব্যাপী এন্ডপয়েন্টের জন্য বাদ দিন বা null ব্যবহার করুন |
এন্ডপয়েন্ট অবজেক্ট-এর সঙ্গে অতিরিক্ত শীর্ষ-স্তরের
secret ক্ষেত্রসহ 201 Created ফেরত দেয়, যাতে কাঁচা স্বাক্ষর কী থাকে — একটি
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"]
}'| ক্ষেত্র | ধরন | বিবরণ |
|---|---|---|
label | স্ট্রিং | |
url | স্ট্রিং | |
events | অ্যারে | |
status | স্ট্রিং | active অথবা disabled। সার্ভার failing হিসেবে চিহ্নিত করা এন্ডপয়েন্ট পুনরায় সক্রিয় করতে active সেট করুন |
agent_id | পূর্ণসংখ্যা | null | এন্ডপয়েন্ট সীমাবদ্ধ করতে একটি এজেন্ট আইডি সেট করুন, অথবা প্রতিষ্ঠানজুড়ে করতে null সেট করুন |
আপডেট করা এন্ডপয়েন্ট অবজেক্ট-সহ 200 OK ফেরত দেয়।
সাইনিং সিক্রেট রোটেট করুন
কোনো endpoint-এর signing secret প্রতিস্থাপন করুন, যেমন এটি হারিয়ে গেলে বা ফাঁস হয়ে থাকতে পারে। আপনি dashboard-ও ব্যবহার করতে পারেন: Integrations → Webhooks-এর অধীনে endpoint খুলুন (সংস্থা-ব্যাপী এবং এজেন্ট endpoint দুটিই সেখানে তালিকাভুক্ত থাকে) এবং Rotate নির্বাচন করুন।
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
নমুনাগুলো এজেন্টের প্রকৃত কলের মতোই প্লেসহোল্ডার মানসহ
extracted_data.fields-এর অধীনে এজেন্টের নিজস্ব সংগ্রহযোগ্য ডেটা ফিল্ড বহন করে। যে
এজেন্ট কোনো ডেটা সংগ্রহ করে না, তার ক্ষেত্রে কল-সম্পন্ন নমুনা প্রকৃত কলের মতোই
extracted_data: null পাঠায় এবং call.data_extracted নমুনায় fields খালি থাকে
(প্রকৃত কল এমন এজেন্টের জন্য কখনোই ওই ইভেন্ট পাঠায় না)। এজেন্টের কল সারাংশ বন্ধ
থাকলে নমুনার summary হবে null। এজেন্টের এন্ডপয়েন্টে নমুনাটি সেই এজেন্টকে অনুসরণ
করে; প্রতিষ্ঠানব্যাপী এন্ডপয়েন্টে, একটি এজেন্টের ভিত্তিতে এটি তৈরি করতে ঐচ্ছিক
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-এ ডেলিভারি অবিলম্বে বন্ধ হয়;
চলমান পুনরায় চেষ্টাগুলো বাতিল করা হয়।
ডেলিভারি ডিবাগ করুন
কোনো webhook পাঠানো হয়নি বলে সিদ্ধান্ত নেওয়ার আগে
GET /v1/developer/webhook-deliveries পরীক্ষা করুন।
এটি উভয় webhook সিস্টেমের সাম্প্রতিক চেষ্টা দেখায়, যার মধ্যে কল id,
URL অরিজিন, HTTP স্ট্যাটাস, চেষ্টার সংখ্যা, অনুমোদিত ব্যর্থতার বিভাগ এবং পরবর্তী
পুনরায় চেষ্টার সময় অন্তর্ভুক্ত। এটি কখনো ইভেন্ট পে-লোড, ট্রান্সক্রিপ্ট, সংরক্ষিত ত্রুটির লেখা,
রেসপন্স বডি বা URL পাথ ফেরত দেয় না।
আপনি এজেন্ট → একটি এজেন্ট নির্বাচন করুন → Webhooks → সাম্প্রতিক ডেলিভারি-তেও একই সাম্প্রতিক ইতিহাস দেখতে পারেন। সারিগুলোতে এন্ডপয়েন্টের লেবেল এবং সর্বশেষ চেষ্টায় ব্যবহৃত URL অরিজিন দেখা যায়। এটি অপরিবর্তনীয় অডিট লগের পরিবর্তে কার্যক্রমগত অবস্থা: একটি এন্ডপয়েন্ট মুছে ফেললে তার ডেলিভারি সারিগুলোও মুছে যায়।
একটি n8n 404-এর ক্ষেত্রে, প্রথমে নিশ্চিত করুন যে ওয়ার্কফ্লোটি সক্রিয়, POST গ্রহণ করে এবং
পরীক্ষার URL-এর পরিবর্তে প্রোডাকশন webhook URL ব্যবহার করে। একটি 401 বা 403 নির্দেশ করে
প্রমাণীকরণ বা স্বাক্ষর যাচাইকরণের সমস্যা; টাইমআউট নির্দেশ করে গন্তব্যের লেটেন্সি
বা প্রাপ্যতার সমস্যা; TLS ত্রুটি নির্দেশ করে সার্টিফিকেট চেইন, হোস্টনাম বা মেয়াদ শেষ হওয়ার সমস্যা।