ปลายทาง Webhook

จัดการ URL ของ webhook หลายรายการด้วยข้อมูลลับและตัวกรองเหตุการณ์สำหรับแต่ละปลายทาง

ระบบ webhook แบบปลายทางช่วยให้คุณลงทะเบียนปลายทางได้ หลายรายการ ต่อองค์กร โดยแต่ละรายการมี secret สถานะ และการสมัครรับข้อมูลสำหรับชุดย่อยของประเภทเหตุการณ์เป็นของตนเอง นี่คือ รูปแบบที่แนะนำสำหรับการผสานรวมใหม่ทั้งหมด

เปรียบเทียบกับ webhook URL เดียวแบบเดิม ซึ่งคงไว้เพื่อความเข้ากันได้กับเวอร์ชันก่อนหน้า แต่รองรับเพียงหนึ่ง 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 — ตั้งค่าอัตโนมัติเมื่อการส่งข้อมูลไปยังเอนด์พอยต์ใช้ กำหนดการลองใหม่ทั้งหมดจนหมด (8 ครั้งภายใน 24 ชั่วโมง) โดย ไม่เคยได้รับ 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"]

ฟิลด์คำขอ#

ส่งคืน 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 พร้อม ออบเจ็กต์ปลายทาง ที่อัปเดตแล้ว

ส่งการนำส่งทดสอบ#

ส่งเหตุการณ์ webhook.test แบบสังเคราะห์ไปยังปลายทางหนึ่งรายการผ่านไปป์ไลน์การนำส่งตามปกติ ซึ่งรวมถึงการซีเรียลไลซ์ JSON แบบมาตรฐาน X-ThunderPhone-Signature การบันทึกการนำส่ง และการติดตามการลองใหม่ การทดสอบจะกำหนดเป้าหมายไปยังปลายทางที่เลือกโดยไม่คำนึงถึงตัวกรอง 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 จะหยุดทันที การลองใหม่ที่กำลังดำเนินการอยู่จะถูกยกเลิก

ดีบักการนำส่ง#

ก่อนสรุปว่าไม่ได้ส่ง webhook ให้ตรวจสอบ GET /v1/developer/webhook-deliveries โดยจะแสดงการลองล่าสุดจากระบบ webhook ทั้งสองระบบ รวมถึงรหัสการโทร ต้นทาง URL สถานะ HTTP จำนวนครั้งที่ลอง หมวดหมู่ความล้มเหลวที่อนุญาต และเวลาลองใหม่ครั้งถัดไป จะไม่ส่งคืนเพย์โหลดเหตุการณ์ ทรานสคริปต์ ข้อความข้อผิดพลาดที่จัดเก็บ เนื้อหาการตอบกลับ หรือพาธ URL

คุณยังดูประวัติล่าสุดเดียวกันได้ที่ เอเจนต์ → เลือกเอเจนต์ → Webhooks → การนำส่งล่าสุด แถวจะแสดงป้ายกำกับปลายทางและต้นทาง URL ที่ใช้ในการลองล่าสุด นี่คือสถานะการดำเนินงาน ไม่ใช่บันทึกการตรวจสอบถาวร การลบปลายทางจะลบแถวการนำส่งของปลายทางนั้นด้วย

สำหรับ 404 ของ n8n ให้ยืนยันก่อนว่าเวิร์กโฟลว์ทำงานอยู่ รับ POST และใช้ URL ของ webhook สำหรับการใช้งานจริงแทน URL ทดสอบ 401 หรือ 403 บ่งชี้ปัญหาการตรวจสอบสิทธิ์หรือการตรวจสอบลายเซ็น ส่วนการหมดเวลาบ่งชี้ความหน่วงหรือความพร้อมใช้งานของปลายทาง และข้อผิดพลาด TLS บ่งชี้ปัญหาห่วงโซ่ใบรับรอง ชื่อโฮสต์ หรือวันหมดอายุ

ที่เกี่ยวข้อง#