ปลายทาง Webhook

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

เปรียบเทียบกับ webhook แบบ URL เดียวรุ่นเก่า ซึ่งคงไว้เพื่อความเข้ากันได้แบบย้อนหลัง แต่รองรับเพียงหนึ่ง URL ต่อองค์กร

ปลายทาง

ออบเจ็กต์ปลายทาง

{
  "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"
}

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

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

• telephony.incoming, telephony.complete, telephony.tool
• web.incoming, web.complete, web.tool
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

สถานะปลายทาง

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

ส่งกลับอาร์เรย์ของออบเจ็กต์ปลายทาง

สร้างเอนด์พอยต์

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 พร้อม ออบเจ็กต์ Endpoint ที่อัปเดตแล้ว และฟิลด์ 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 พร้อม ออบเจ็กต์ Endpoint ที่อัปเดตแล้ว

ส่งการจัดส่งทดสอบ

ส่งเหตุการณ์ 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 ของเอนด์พอยต์ได้ หากความพยายามครั้งแรกล้มเหลว การจัดส่งจะทำตามกำหนดการ ลองใหม่เดียวกับการจัดส่งเหตุการณ์ปกติ

ลบเอนด์พอยต์

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

ส่งคืน 204 No Content การจัดส่งไปยัง URL จะหยุดทันที และการลองใหม่ที่กำลังดำเนินการอยู่จะถูกยกเลิก

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