Webhook Endpoint

สร้าง จุดเชื่อมต่อ Webhook

สร้าง Webhook ที่ URL HTTP(S) แบบ absolute และแนะนำ HTTPS สำหรับ production status เป็น active หรือ inactive subscribed_events รับ public event หรือ ["*"] และ max_attempts 0..5 เมื่อสร้าง endpoint ของบัญชีเป็น active หากบัญชีเดียวกันมี endpoint active อื่นอยู่แล้ว จะคืน 409 account_webhook_already_exists (40008) สิทธิ์รับเหตุการณ์โทรควบคุมด้วย is_beta ของเวิร์กสเปซ สำหรับเวิร์กสเปซทดสอบ subscribed_events ที่เป็น *, รายการว่าง หรือไม่ระบุฟิลด์จะรวมเหตุการณ์โทร ส่วนรายการเฉพาะจะรับเฉพาะเหตุการณ์ที่ระบุ เวิร์กสเปซทั่วไปใช้ wildcard ได้แต่จะไม่ได้รับเหตุการณ์โทร การระบุสมัครเหตุการณ์โทรโดยตรงยังคงได้ 403 beta_feature_not_enabled ตรวจสิทธิ์ใหม่ทุกครั้งที่ส่ง ลองใหม่ และเล่นซ้ำ dead letter หากตรวจสอบล้มเหลวจะไม่อนุญาต ส่วนบันทึกการโทร message.* เป็นอิสระจากสิทธิ์นี้

POSThttps://api.unifyport.ai/v1/webhook-endpoints

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

all

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

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

เมื่อสร้างหรือเปิดใช้งานปลายทางเฉพาะบัญชีอีกครั้ง account_id เดียวมีปลายทาง active ได้เพียงหนึ่งรายการ หากขัดแย้งจะได้รับ 409 account_webhook_already_exists (40008) มีปลายทางบัญชีที่เป็น inactive และปลายทางของเวิร์กสเปซได้หลายรายการ ปลายทางที่เป็น active อยู่แล้วสามารถแก้ไขโดยคง active ได้ รวมถึงการตั้งค่าเดิมที่มีหลาย active

ที่มาของพารามิเตอร์

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

คำขอ

curl -X POST "https://api.unifyport.ai/v1/webhook-endpoints" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

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

ส่วนหัว

X-Api-Key

stringจำเป็น

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

Content-Type

stringจำเป็น

ใช้ application/json เมื่อต้องส่งเนื้อหาของคำขอเป็น JSON

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

account_id

string

ID บัญชีสาธารณะที่ไม่บังคับใน body เช่น acc_example เมื่อสร้างจะผูก endpoint กับบัญชี หากละไว้จะสร้าง endpoint ของเวิร์กสเปซ เมื่ออัปเดตจะตรวจสอบเฉพาะการผูกเดิม หากละไว้จะคงเจ้าของเดิมไว้ ไม่สามารถเปลี่ยนบัญชี เปลี่ยน endpoint ของเวิร์กสเปซเป็น endpoint ของบัญชี หรือล้างการผูกได้ ไม่รับ query, null, สตริงว่าง สตริงที่มีแต่ช่องว่าง หรือฟิลด์ซ้ำ ต้องใช้ชื่อ account_id ตรงตัว หากใช้ตัวพิมพ์ใหญ่เล็กต่างกันใน body หรือ query หรือเจ้าของไม่ตรงกันจะคืน 400 invalid_request หากบัญชีที่ระบุไม่มีอยู่หรือไม่อยู่ในเวิร์กสเปซปัจจุบันจะคืน 404 account_not_found (20020) การตั้งค่าอิสระของบัญชีมีลำดับความสำคัญเหนือการตั้งค่าเวิร์กสเปซ การปิดใช้งานหรือไม่ได้สมัครเหตุการณ์บางประเภทจะไม่กลับไปใช้เวิร์กสเปซ เมื่อลบ endpoint อิสระตัวสุดท้าย การส่งครั้งแรกของเหตุการณ์ถัดไปจะกลับมาสืบทอดการตั้งค่าเวิร์กสเปซ การตรวจสอบข้อขัดแย้งเมื่อเปิดใช้งานพิจารณาเฉพาะ endpoint active อื่นที่มี account_id เดียวกัน endpoint ของเวิร์กสเปซไม่อยู่ภายใต้ข้อจำกัดนี้ ดูเงื่อนไขใน status

minLength: 1 · pattern: \S

url

stringจำเป็น

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

format: uri

status

stringจำเป็น

สถานะ endpoint: active หรือ inactive เมื่อสร้าง endpoint active ของบัญชีหรือเปลี่ยน inactive→active หากบัญชีเดียวกันมี endpoint active อื่นอยู่แล้ว จะคืน 409 account_webhook_already_exists (40008) บัญชีมี endpoint inactive ได้หลายตัว และเวิร์กสเปซมี endpoint ได้หลายตัว การอัปเดต endpoint ที่เป็น active อยู่แล้วและยังคง active ทำได้ รวมถึงการตั้งค่าเก่าที่มีหลาย endpoint active โดยจะไม่ล้าง endpoint เก่าโดยอัตโนมัติ

enum: active, inactive

subscribed_events[]

string[]

การสมัคร public standard event หากละเว้น ใช้อาร์เรย์ว่าง หรือมี * จะรับ public event ทั้งหมด รวมถึง contact.updated ที่เพิ่มใหม่ แต่ไม่รวม provider.raw_event หากต้องการเฉพาะบาง event ให้ระบุชื่ออย่างชัดเจน

signing_secret

string

secret สำหรับลงนาม Webhook แบบเลือก ในตัวอย่างให้ใช้ค่าตัวแทน

retry_policy

object

max_attempts คือจำนวน retry หลังการส่งครั้งแรก ค่าเริ่มต้น 3 ช่วง 0–5 และ 0 หมายถึงส่งครั้งแรกเท่านั้น

max_attempts

integer

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

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

ตรวจการตั้งค่าที่ส่งกลับ ก่อนทดสอบการส่ง ปลายทางต้องเป็น active และสมัครรับเหตุการณ์นั้น ตรวจลายเซ็นเฉพาะเมื่อ signing_enabled=true บันทึกเหตุการณ์ก่อน แล้วส่ง 2xx เพื่อยืนยันการรับ

การตอบกลับ 201 Created

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook",
    "status": "active",
    "subscribed_events": [
      "*"
    ],
    "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

การตอบกลับ

201

201 Created

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

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

404

Not Found

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

409

Conflict

การดำเนินการขัดแย้งกับบัญชีของผู้ให้บริการหรือทรัพยากรที่มีอยู่

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

ตัวอย่าง · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

beta_feature_not_enabled · 41002 · 403

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

ตัวอย่าง · 403 · 41002

{
  "request_id": "req_example",
  "error": {
    "code": "beta_feature_not_enabled",
    "numeric_code": "41002",
    "message": "Beta feature not enabled"
  }
}

workspace_override_forbidden · 11002 · 403

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

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-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"
  }
}

account_webhook_already_exists · 40008 · 409

ใช้ account_id เรียกดูปลายทางเฉพาะบัญชี แล้วแก้ไขปลายทาง active ที่มีอยู่ หากต้องการเปลี่ยน ให้ปิดใช้งาน active เดิมก่อนเปิดปลายทางอื่น ห้ามลองสร้างหรือเปิดใช้งานอีกครั้งโดยอัตโนมัติ

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

ตัวอย่าง · 409 · 40008

{
  "request_id": "req_example_webhook_conflict",
  "error": {
    "code": "account_webhook_already_exists",
    "numeric_code": "40008",
    "message": "Account already has an active webhook endpoint"
  }
}

create_webhook_endpoint_failed · 40001 · 500

สร้าง จุดเชื่อมต่อ Webhook: ข้อผิดพลาดที่ยังไม่จัดประเภทขัดจังหวะการเปลี่ยนแปลง ต้องยืนยันสถานะสุดท้าย

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 40001

{
  "request_id": "req_example",
  "error": {
    "code": "create_webhook_endpoint_failed",
    "numeric_code": "40001",
    "message": "Failed to create webhook endpoint"
  }
}