ThunderPhone v3 พร้อมให้ใช้งานแล้วเริ่มใช้งานได้ด้วยตัวเอง ราคาเริ่มต้น 2 เซนต์ต่อนาที.อ่านประกาศเปิดตัว

Webhooks

ปลายทาง Webhook

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

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

เปรียบเทียบกับ webhook แบบ URL เดียวเดิม ซึ่งคงไว้เพื่อรองรับการทำงานย้อนหลัง แต่รองรับ 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+ตรวจสอบผลลัพธ์การจัดส่งปลายทางล่าสุดและการจัดส่งแบบเดิม

ออบเจ็กต์ 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"
}
ฟิลด์ประเภทคำอธิบาย
idUUIDรหัส Endpoint
labelstringชื่อที่แสดง 1–120 อักขระ
urlstringURL แบบ HTTPS; อนุญาต http://localhost สำหรับการพัฒนา
eventsอาร์เรย์ของ stringประเภทเหตุการณ์ที่สมัครรับข้อมูล (ดูค่าที่ใช้ได้) อาร์เรย์ว่างจะสมัครรับข้อมูลทุกเหตุการณ์ ยกเว้นเหตุการณ์ที่ต้องระบุอย่างชัดเจน (telephony.turn / web.turn / call.status_changed)
statusstringactive, disabled (หยุดชั่วคราวด้วยตนเอง) หรือ failing (ตั้งค่าโดยอัตโนมัติเมื่อการส่งข้อมูลใช้กำหนดการลองใหม่ 24 ชั่วโมงจนหมดโดยไม่ได้รับ 2xx แม้แต่ครั้งเดียว)
agent_idinteger | nullเอเจนต์ที่ Endpoint นี้กำหนดขอบเขตไว้; null หมายถึงทั้งองค์กร
agent_namestring | nullชื่อของเอเจนต์ที่กำหนดขอบเขต หรือ null สำหรับ Endpoint ระดับองค์กร
secret_hintstringอักขระ 4 ตัวแรกและ 4 ตัวสุดท้ายของข้อมูลลับสำหรับการลงนาม พร้อมจุดไข่ปลา (a1b2…9f0e) — เพียงพอสำหรับอ้างอิงข้ามกับข้อมูลลับที่คุณบันทึกไว้ในเครื่อง โดยไม่เปิดเผยค่าทั้งหมด
paused_attimestamp | nullเวลาที่ ThunderPhone ตั้งค่า Endpoint เป็น failing ค่าเป็น null ขณะที่อยู่ในสถานะ active หรือ disabled
pause_last_errorstringข้อผิดพลาดในการส่งข้อมูลล่าสุดเมื่อ Endpoint ถูกหยุดชั่วคราว เช่น HTTP 503: Service Unavailable ว่างเปล่ายกเว้นเมื่อเป็น failing
pause_undelivered_countinteger | nullเหตุการณ์ที่ไม่ได้ส่งนับตั้งแต่การส่งข้อมูลสำเร็จครั้งล่าสุดของ Endpoint โดยนับเมื่อถูกหยุดชั่วคราว
created_at, updated_attimestamp

ประเภทเหตุการณ์ที่ใช้ได้

ระบบตรวจสอบ events กับชุดนี้โดยตรง — ค่าที่อยู่นอกเหนือจากรายการ จะส่งคืน 400 ดูแค็ตตาล็อกเหตุการณ์สำหรับรูปแบบ payload ของแต่ละประเภท

  • 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 ได้โดยตรง หากต้องการรับ เหตุการณ์เหล่านี้ ให้สร้าง endpoint ระดับองค์กรด้วย events: [] รายการเหตุการณ์ที่ว่างเปล่าจะได้รับทุกเหตุการณ์ที่รองรับ ยกเว้น telephony.turn, web.turn และ call.status_changed ซึ่งต้องเลือกโดยตรง

สถานะของ Endpoint

  • active — การส่งดำเนินไปตามปกติ
  • disabled — หยุดชั่วคราวด้วยตนเองผ่าน PATCH ไม่มีการส่งคำขอ เรา จะไม่เปลี่ยนสถานะของปลายทาง disabled การเปลี่ยนกลับเป็น active เป็นการตัดสินใจของคุณเสมอ
  • failing — ตั้งค่าโดยอัตโนมัติเมื่อการส่งไปยังปลายทางใช้ กำหนดการลองใหม่ทั้งหมด (8 ครั้งภายใน 24 ชั่วโมง) โดยไม่ได้รับ 2xx เลย ปลายทางที่ล้มเหลวจะไม่ได้รับทราฟฟิกเพิ่มเติม เราจะส่งอีเมลถึงเจ้าของและผู้ดูแลระบบขององค์กรเมื่อเกิดเหตุการณ์นี้ และ แดชบอร์ดจะแสดงปลายทางที่หยุดชั่วคราวพร้อมปุ่ม เปิดใช้งานอีกครั้ง เมื่อแก้ไขปลายทางแล้ว ให้ PATCH สถานะกลับเป็น active การส่งที่กำหนดการลองใหม่ยังไม่หมดอายุจะดำเนินต่อจากจุดเดิม

แสดงรายการ Endpoint

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

ฟิลด์คำขอ

ฟิลด์ชนิดจำเป็นคำอธิบาย
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
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"]
  }'
ฟิลด์ประเภทคำอธิบาย
labelstring
urlstring
eventsarray
statusstringactive หรือ disabled ตั้งค่าเป็น active เพื่อเปิดใช้เอนด์พอยต์อีกครั้ง หากเซิร์ฟเวอร์ทำเครื่องหมายเป็น failing
agent_idinteger | 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_idsอาร์เรย์ของ UUIDทุกเอนด์พอยต์ที่ขณะนี้ใช้ความลับใหม่

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

ส่งเหตุการณ์ 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 มีฟิลด์ข้อมูลที่เอเจนต์ต้องเก็บรวบรวมของเอเจนต์เองอยู่ภายใต้ extracted_data.fields พร้อมค่าตัวแทน เช่นเดียวกับการโทรจริงของเอเจนต์ สำหรับ เอเจนต์ที่ไม่เก็บรวบรวมข้อมูล ตัวอย่างการโทรเสร็จสิ้นจะส่ง extracted_data: null เช่นเดียวกับการโทรจริงของเอเจนต์ และตัวอย่าง call.data_extracted จะมี fields ว่างเปล่า (การโทรจริงจะไม่ส่งเหตุการณ์นั้นสำหรับเอเจนต์ดังกล่าว) summary ของตัวอย่างจะเป็น null เมื่อปิดสรุปการโทรของเอเจนต์ สำหรับ ปลายทางของเอเจนต์ ตัวอย่างจะอ้างอิงตามเอเจนต์นั้น สำหรับปลายทางระดับองค์กร ให้ส่ง 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 ซึ่งแสดงการลองล่าสุดจากระบบเว็บฮุกทั้งสองระบบ รวมถึงรหัสการโทร ต้นทางของ URL สถานะ HTTP จำนวนครั้งที่ลอง หมวดหมู่ความล้มเหลวที่อยู่ในรายการอนุญาต และเวลา ลองใหม่ครั้งถัดไป โดยจะไม่ส่งคืนเพย์โหลดเหตุการณ์ บันทึกการสนทนา ข้อความข้อผิดพลาดที่จัดเก็บไว้ เนื้อหาการตอบกลับ หรือเส้นทาง URL

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

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


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