Webhook এন্ডপয়েন্ট

প্রতি এন্ডপয়েন্টের জন্য আলাদা সিক্রেট এবং ইভেন্ট ফিল্টারসহ একাধিক webhook URL পরিচালনা করুন।

এন্ডপয়েন্ট-ভিত্তিক webhook সিস্টেম আপনাকে প্রতি সংস্থার জন্য একাধিক গন্তব্য নিবন্ধন করতে দেয়, প্রতিটির নিজস্ব secret, নিজস্ব status এবং event type-এর একটি উপসেটের জন্য নিজস্ব subscription থাকে। নতুন সব integration-এর জন্য এটিই প্রস্তাবিত মডেল।

লিগ্যাসি একক-URL webhook-এর সঙ্গে তুলনা করুন, যেটি backward compatibility-এর জন্য রাখা হয়েছে, তবে প্রতি সংস্থায় শুধু একটি 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 ফেরত আসে। প্রতিটি ধরনের payload কাঠামোর জন্য ইভেন্ট ক্যাটালগ দেখুন।

• 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"]

রিকোয়েস্ট ফিল্ড#

এন্ডপয়েন্ট অবজেক্ট-এর সঙ্গে অতিরিক্ত শীর্ষ-স্তরের 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"]
  }'

আপডেট করা এন্ডপয়েন্ট অবজেক্ট-সহ 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 পরিদর্শন করুন। এটি কল id, URL অরিজিন, HTTP স্ট্যাটাস, প্রচেষ্টার সংখ্যা, অনুমোদিত তালিকাভুক্ত ব্যর্থতার বিভাগ এবং পরবর্তী পুনঃচেষ্টার সময়সহ উভয় ওয়েবহুক সিস্টেমের সাম্প্রতিক প্রচেষ্টা দেখায়। এটি কখনও ইভেন্ট পেলোড, ট্রান্সক্রিপ্ট, সংরক্ষিত ত্রুটির লেখা, রেসপন্স বডি বা URL পাথ ফেরত দেয় না।

আপনি এজেন্ট → একটি এজেন্ট নির্বাচন করুন → ওয়েবহুক → সাম্প্রতিক ডেলিভারি-তেও একই সাম্প্রতিক ইতিহাস দেখতে পারেন। সারিগুলোতে এন্ডপয়েন্ট লেবেল এবং সর্বশেষ প্রচেষ্টায় ব্যবহৃত URL অরিজিন দেখানো হয়। এটি অপরিবর্তনীয় অডিট লগের পরিবর্তে অপারেশনাল অবস্থা: একটি এন্ডপয়েন্ট মুছে দিলে তার ডেলিভারি সারিগুলোও মুছে যায়।

একটি n8n 404-এর ক্ষেত্রে, প্রথমে নিশ্চিত করুন যে ওয়ার্কফ্লো সক্রিয়, POST গ্রহণ করে এবং পরীক্ষার URL-এর পরিবর্তে প্রোডাকশন ওয়েবহুক URL ব্যবহার করে। একটি 401 বা 403 প্রমাণীকরণ বা স্বাক্ষর যাচাইকরণের দিকে নির্দেশ করে; টাইমআউট গন্তব্যের বিলম্ব বা প্রাপ্যতার দিকে নির্দেশ করে; TLS ত্রুটি সার্টিফিকেট চেইন, হোস্টনাম বা মেয়াদ শেষ হওয়ার দিকে নির্দেশ করে।

সম্পর্কিত#