Open in
ปลายทาง Webhook
จัดการ URL ของ webhook หลายรายการด้วยข้อมูลลับและตัวกรองเหตุการณ์สำหรับแต่ละปลายทาง
ระบบ webhook แบบปลายทางช่วยให้คุณลงทะเบียนปลายทางได้ หลายรายการ ต่อองค์กร โดยแต่ละรายการมีซีเคร็ต สถานะ และการสมัครรับประเภทอีเวนต์บางส่วนของตนเอง นี่คือรูปแบบที่แนะนำสำหรับการผสานการทำงานใหม่ทั้งหมด
เปรียบเทียบกับ webhook แบบ URL เดียวเดิม ซึ่งคงไว้เพื่อรองรับการทำงานย้อนหลัง แต่รองรับ 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+ | ตรวจสอบผลลัพธ์การจัดส่งปลายทางล่าสุดและการจัดส่งแบบเดิม |
ออบเจ็กต์ Endpoint
{
"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 | รหัส Endpoint |
label | string | ชื่อที่แสดง 1–120 อักขระ |
url | string | URL แบบ HTTPS; อนุญาต http://localhost สำหรับการพัฒนา |
events | อาร์เรย์ของ string | ประเภทเหตุการณ์ที่สมัครรับข้อมูล (ดูค่าที่ใช้ได้) อาร์เรย์ว่างจะสมัครรับข้อมูลทุกเหตุการณ์ ยกเว้นเหตุการณ์ที่ต้องระบุอย่างชัดเจน (telephony.turn / web.turn / call.status_changed) |
status | string | active, disabled (หยุดชั่วคราวด้วยตนเอง) หรือ failing (ตั้งค่าโดยอัตโนมัติเมื่อการส่งข้อมูลใช้กำหนดการลองใหม่ 24 ชั่วโมงจนหมดโดยไม่ได้รับ 2xx แม้แต่ครั้งเดียว) |
agent_id | integer | null | เอเจนต์ที่ Endpoint นี้กำหนดขอบเขตไว้; null หมายถึงทั้งองค์กร |
agent_name | string | null | ชื่อของเอเจนต์ที่กำหนดขอบเขต หรือ null สำหรับ Endpoint ระดับองค์กร |
secret_hint | string | อักขระ 4 ตัวแรกและ 4 ตัวสุดท้ายของข้อมูลลับสำหรับการลงนาม พร้อมจุดไข่ปลา (a1b2…9f0e) — เพียงพอสำหรับอ้างอิงข้ามกับข้อมูลลับที่คุณบันทึกไว้ในเครื่อง โดยไม่เปิดเผยค่าทั้งหมด |
paused_at | timestamp | null | เวลาที่ ThunderPhone ตั้งค่า Endpoint เป็น failing ค่าเป็น null ขณะที่อยู่ในสถานะ active หรือ disabled |
pause_last_error | string | ข้อผิดพลาดในการส่งข้อมูลล่าสุดเมื่อ Endpoint ถูกหยุดชั่วคราว เช่น HTTP 503: Service Unavailable ว่างเปล่ายกเว้นเมื่อเป็น failing |
pause_undelivered_count | integer | null | เหตุการณ์ที่ไม่ได้ส่งนับตั้งแต่การส่งข้อมูลสำเร็จครั้งล่าสุดของ Endpoint โดยนับเมื่อถูกหยุดชั่วคราว |
created_at, updated_at | timestamp |
ประเภทเหตุการณ์ที่ใช้ได้
ระบบตรวจสอบ events กับชุดนี้โดยตรง — ค่าที่อยู่นอกเหนือจากรายการ
จะส่งคืน 400 ดูแค็ตตาล็อกเหตุการณ์สำหรับรูปแบบ
payload ของแต่ละประเภท
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 ได้โดยตรง หากต้องการรับ
เหตุการณ์เหล่านี้ ให้สร้าง endpoint ระดับองค์กรด้วย events: [] รายการเหตุการณ์ที่ว่างเปล่าจะได้รับทุกเหตุการณ์ที่รองรับ ยกเว้น telephony.turn, web.turn และ
call.status_changed ซึ่งต้องเลือกโดยตรง
สถานะของ Endpoint
active— การส่งดำเนินไปตามปกติdisabled— หยุดชั่วคราวด้วยตนเองผ่านPATCHไม่มีการส่งคำขอ เรา จะไม่เปลี่ยนสถานะของปลายทางdisabledการเปลี่ยนกลับเป็นactiveเป็นการตัดสินใจของคุณเสมอfailing— ตั้งค่าโดยอัตโนมัติเมื่อการส่งไปยังปลายทางใช้ กำหนดการลองใหม่ทั้งหมด (8 ครั้งภายใน 24 ชั่วโมง) โดยไม่ได้รับ 2xx เลย ปลายทางที่ล้มเหลวจะไม่ได้รับทราฟฟิกเพิ่มเติม เราจะส่งอีเมลถึงเจ้าของและผู้ดูแลระบบขององค์กรเมื่อเกิดเหตุการณ์นี้ และ แดชบอร์ดจะแสดงปลายทางที่หยุดชั่วคราวพร้อมปุ่ม เปิดใช้งานอีกครั้ง เมื่อแก้ไขปลายทางแล้ว ให้PATCHสถานะกลับเป็นactiveการส่งที่กำหนดการลองใหม่ยังไม่หมดอายุจะดำเนินต่อจากจุดเดิม
แสดงรายการ Endpoint
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"ส่งคืนอาร์เรย์ของออบเจ็กต์ Endpoint
ส่ง ?agent_id=42 เพื่อส่งคืนเฉพาะ Endpoint ที่กำหนดขอบเขตไว้สำหรับเอเจนต์นั้น
Endpoint ที่กำหนดขอบเขตตามเอเจนต์
Endpoint ระดับองค์กรจะรับทุกเหตุการณ์ที่ตรงกัน Endpoint ที่มี
agent_id จะรับเฉพาะเหตุการณ์ที่ตรงกันสำหรับสายที่เอเจนต์นั้นดูแล
เหตุการณ์ที่ไม่มีบริบทเอเจนต์ เช่น alert.triggered จะไม่ส่งถึง Endpoint นี้
คุณยังสามารถสร้างและจัดการ Endpoint เหล่านี้ได้จากส่วน
Webhook ของเครื่องมือสร้างเอเจนต์
สร้างเอนด์พอยต์
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 | สตริง | ใช่ | URL แบบ HTTPS (อนุญาตให้ใช้ http ได้เฉพาะสำหรับ localhost / 127.0.0.1) |
events | อาร์เรย์ | ไม่ | หากว่างเปล่าหรือไม่ระบุ จะสมัครรับอีเวนต์ทั้งหมด ยกเว้น telephony.turn / web.turn / call.status_changed ซึ่งต้องสมัครรับอย่างชัดเจน ต้องใช้ค่าที่ระบุในประเภทอีเวนต์ที่ใช้ได้; ระบบจะลบค่าที่ซ้ำ |
agent_id | จำนวนเต็ม | null | ไม่ | จำกัดการส่งไปยังเอเจนต์ในองค์กรนี้; ไม่ต้องระบุหรือใช้ null สำหรับเอนด์พอยต์ระดับองค์กร |
ส่งคืน 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"]
}'| ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|
label | string | |
url | string | |
events | array | |
status | string | active หรือ disabled ตั้งค่าเป็น active เพื่อเปิดใช้เอนด์พอยต์อีกครั้ง หากเซิร์ฟเวอร์ทำเครื่องหมายเป็น failing |
agent_id | integer | 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
มีฟิลด์ข้อมูลที่เอเจนต์ต้องเก็บรวบรวมของเอเจนต์เองอยู่ภายใต้
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 จะหยุดทันที
และการลองใหม่ที่กำลังดำเนินการจะถูกยกเลิก
ดีบักการนำส่ง
ก่อนสรุปว่าไม่ได้ส่งเว็บฮุก ให้ตรวจสอบ
GET /v1/developer/webhook-deliveries
ซึ่งแสดงการลองล่าสุดจากระบบเว็บฮุกทั้งสองระบบ รวมถึงรหัสการโทร
ต้นทางของ URL สถานะ HTTP จำนวนครั้งที่ลอง หมวดหมู่ความล้มเหลวที่อยู่ในรายการอนุญาต และเวลา
ลองใหม่ครั้งถัดไป โดยจะไม่ส่งคืนเพย์โหลดเหตุการณ์ บันทึกการสนทนา ข้อความข้อผิดพลาดที่จัดเก็บไว้
เนื้อหาการตอบกลับ หรือเส้นทาง URL
คุณยังสามารถดูประวัติล่าสุดเดียวกันได้ใน เอเจนต์ → เลือกเอเจนต์ → เว็บฮุก → การนำส่งล่าสุด แถวจะแสดงป้ายกำกับปลายทางและต้นทางของ URL ที่ใช้ในการลองล่าสุด ข้อมูลนี้เป็นสถานะการดำเนินงาน ไม่ใช่บันทึกการตรวจสอบที่เปลี่ยนแปลงไม่ได้ การลบปลายทาง จะลบแถวการนำส่งของปลายทางนั้นด้วย
สำหรับ 404 ของ n8n ให้ยืนยันก่อนว่าเวิร์กโฟลว์เปิดใช้งานอยู่ รองรับ POST และใช้
URL เว็บฮุกสำหรับการใช้งานจริงแทน URL ทดสอบ 401 หรือ 403 บ่งชี้ถึง
การตรวจสอบสิทธิ์หรือการตรวจสอบลายเซ็น การหมดเวลาบ่งชี้ถึงความหน่วง
หรือความพร้อมใช้งานของปลายทาง ส่วนข้อผิดพลาด TLS บ่งชี้ถึงสายโซ่ใบรับรอง ชื่อโฮสต์ หรือวันหมดอายุ