เอกสารอ้างอิง API

Webhook Endpoint

ดู จุดเชื่อมต่อ Webhook

คืน config ของ จุดเชื่อมต่อ Webhook หนึ่งรายการ

GEThttps://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}

ช่องทางที่รองรับ

all

ก่อนเรียกใช้

ใช้ X-Api-Key ของ workspace เจ้าของทรัพยากรบนเซิร์ฟเวอร์ แทนค่าตัวอย่างทั้งหมดก่อนเรียกใช้

ที่มาของพารามิเตอร์
account_id
รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี

พารามิเตอร์คำขอ

ส่วนหัว

X-Api-Key
stringจำเป็น

API key ของพื้นที่ทำงาน ระบบจะระบุพื้นที่ทำงานจากส่วนหัวนี้

พารามิเตอร์ใน path

endpoint_id
stringจำเป็น

ตัวระบุที่ใช้ใน route ของ webhook endpoints

พารามิเตอร์ Query

account_id
string

ID บัญชีสาธารณะที่ไม่บังคับ เช่น acc_example ห้ามเป็นสตริงว่าง มีแต่ช่องว่าง หรือระบุซ้ำ ต้องใช้ชื่อ account_id ตรงตัว หากใช้ตัวพิมพ์ใหญ่เล็กต่างกันจะคืน 400 invalid_request ไม่ถือว่าละไว้ ในการแสดงรายการ หากละไว้จะคืนเฉพาะ endpoint ของเวิร์กสเปซ หากระบุจะคืนเฉพาะการตั้งค่าอิสระของบัญชีนั้น (data=[] หากไม่มี โดยไม่รวมการตั้งค่าที่สืบทอดจากเวิร์กสเปซ) การดูรายละเอียด ปิดใช้งาน และลบจะตรวจสอบเฉพาะบัญชีเจ้าของเดิม หากไม่ตรงกันจะคืน 400 invalid_request หากบัญชีที่ระบุไม่มีอยู่หรือไม่อยู่ในเวิร์กสเปซปัจจุบันจะคืน 404 account_not_found (20020)

minLength: 1 · pattern: \S

เนื้อหาของคำขอ

จุดเชื่อมต่อนี้ไม่ต้องใช้เนื้อหา JSON

ทำความเข้าใจผลลัพธ์

อ่านขอบเขตของปลายทาง status เหตุการณ์ที่สมัครรับ signing_enabled และนโยบายลองใหม่ การเรียกดูสำเร็จยืนยันเฉพาะการตั้งค่า ไม่ได้ยืนยันการส่งเหตุการณ์

การตอบกลับ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": [
      "message.received"
    ],
    "signing_enabled": true,
    "retry_policy": {
      "max_attempts": 3
    }
  }
}

เนื้อหาการตอบกลับ

id
string

ตัวระบุ จุดเชื่อมต่อ Webhook (we_...)

account_id
string

ID บัญชีสาธารณะของ endpoint อิสระของบัญชี สำหรับ endpoint ของเวิร์กสเปซจะละฟิลด์นี้ ไม่คืน null

minLength: 1

url
string

URL HTTP(S) แบบ absolute ที่รับ Webhook และแนะนำ HTTPS สำหรับ production

format: uri

status
string

สถานะ จุดเชื่อมต่อ: active หรือ inactive

enum: active, inactive

subscribed_events[]
string[]

public standard event ของ จุดเชื่อมต่อ; ["*"] หมายถึง public event ที่เวิร์กสเปซมีสิทธิ์รับโดยไม่รวม provider.raw_event

signing_enabled
boolean

เป็น true เมื่อมีการตั้ง signing secret และการนำส่งถูกลงนาม

retry_policy
object

max_attempts นับ retry หลังการส่งครั้งแรก ค่าเริ่มต้น 3 ช่วง 0–5

max_attempts
integer

จำนวน retry หลังการส่งครั้งแรกที่ตั้งไว้ ตั้งแต่ 0 ถึง 5

การตอบกลับ

200

200 OK

คำขอสำเร็จ ดูตัวอย่างเนื้อหาตอบกลับด้านบน

400

Bad Request

เนื้อหาของคำขอ path หรือพารามิเตอร์ไม่ถูกต้อง

401

Unauthorized

ส่วนหัว X-Api-Key หายไปหรือไม่ถูกต้อง

403

Forbidden

ระบบระบุคำขอได้ แต่ไม่อนุญาตให้ดำเนินการนี้

404

Not Found

ไม่พบทรัพยากรที่ร้องขอ โปรดตรวจสอบ error.code ร่วมกับการดำเนินการปัจจุบัน

500

Internal Server Error

บริการพบข้อผิดพลาดที่ไม่คาดคิด

เมื่อคำขอล้มเหลว

ตรวจ HTTP และ error.code/numeric_code เก็บ request_id แล้วแก้พารามิเตอร์ ยืนยันตัวตนต่อ หรือตรวจ runtime ตามสาเหตุ ตรวจผลครั้งก่อนก่อนส่งหรือเขียนซ้ำ อ้างอิงรหัสข้อผิดพลาด

อ่านสถานะ HTTP, error.code และ error.numeric_code ร่วมกับคำสั่งที่เรียก รหัสตัวเลขเป็นสตริง เก็บ request_id เพื่อตรวจปัญหา ค่านี้ไม่ใช่คีย์ป้องกันการทำซ้ำหรือรหัสงาน

invalid_request · 10000 · 400

ตรวจ JSON และฟิลด์ที่จำเป็น

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
invalid_target_workspace · 11003 · 400

เวิร์กสเปซเป้าหมายที่กำหนดทับว่างหรือรูปแบบไม่ถูกต้อง ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
invalid_api_key · 11001 · 401

ตรวจว่า API Key ถูกต้องและเปิดใช้งานอยู่

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

เพิ่มส่วนหัว X-Api-Key

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

ตัวอย่าง · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

คำขอพยายามระบุเวิร์กสเปซทับโดย API Key นี้ไม่มีสิทธิ์ ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
account_not_found · 20020 · 404

ตรวจ account_id และใช้ X-Api-Key ของเวิร์กสเปซเจ้าของบัญชี คีย์ปัจจุบันไม่สามารถเข้าถึงบัญชีที่ไม่พบในเวิร์กสเปซนี้

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 404 · 20020
{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
target_workspace_not_found · 11004 · 404

ไม่พบเวิร์กสเปซที่กำหนดทับหรือใช้งานไม่ได้ ตรวจเจ้าของเวิร์กสเปซ ลบเฮดเดอร์กำหนดทับ และใช้ API Key ของเวิร์กสเปซเป้าหมาย การส่งซ้ำไม่เพิ่มสิทธิ์

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
get_webhook_endpoint_failed · 40002 · 500

ดู จุดเชื่อมต่อ Webhook: บริการไม่สามารถให้ผลการค้นหาที่ใช้ได้

วิธีจัดการและลองใหม่: เก็บ request_id และตรวจรหัสเป้าหมายกับสิทธิ์เข้าถึงของบัญชี ตรวจสาเหตุก่อนอ่านใหม่ การค้นหาล้มเหลวไม่ได้แปลว่าข้อมูลว่างหรือไม่มีทรัพยากร

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 40002
{
  "request_id": "req_example",
  "error": {
    "code": "get_webhook_endpoint_failed",
    "numeric_code": "40002",
    "message": "Failed to get webhook endpoint"
  }
}
get_webhook_endpoint_failed · 40006 · 500

ไม่พบปลายทาง Webhook ในขอบเขตนี้ GET, PATCH และการปิดใช้งานคง code ของแต่ละคำสั่งและ HTTP 500 พร้อม numeric_code=40006 รหัสย่อยนี้ไม่ใช้กับ DELETE ที่ทำซ้ำได้ปลอดภัย ซึ่งส่ง 204 เมื่อไม่พบปลายทาง

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 40006
{
  "request_id": "req_example",
  "error": {
    "code": "get_webhook_endpoint_failed",
    "numeric_code": "40006",
    "message": "Webhook endpoint not found"
  }
}