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

Webhook Endpoint

อัปเดต จุดเชื่อมต่อ Webhook

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

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

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

all

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

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

PATCH จะแทนที่การตั้งค่า Webhook ให้ส่งค่าทั้งหมดที่ต้องการเก็บไว้ หากละ signing_secret จะปิดลายเซ็น หากละ subscribed_events จะกลับไปรับเหตุการณ์สาธารณะทั้งหมด หากละ retry_policy/max_attempts จะกลับไปลองใหม่ 3 ครั้งตามค่าเริ่มต้น อ่านการตั้งค่าปัจจุบันก่อนและส่งคีย์ลายเซ็นที่คุณบันทึกไว้

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

ส่วนหัว

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

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

Content-Type
stringจำเป็น

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

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

endpoint_id
stringจำเป็น

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

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

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)

minLength: 1 · pattern: \S

url
stringจำเป็น

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

format: uri

status
stringจำเป็น

สถานะ endpoint: active หรือ inactive

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

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

ตั้งค่าสำเร็จไม่ได้ยืนยันว่าส่งเหตุการณ์แล้ว ให้สร้างเหตุการณ์และตรวจสอบการรับ ลายเซ็น และการตอบรับที่ปลายทาง

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

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook-updated",
    "status": "inactive",
    "subscribed_events": [
      "message.delivered",
      "message.read"
    ],
    "signing_enabled": false,
    "retry_policy": {
      "max_attempts": 1
    }
  }
}

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

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

ไม่พบทรัพยากรของ provider ที่ร้องขอ

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

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

invalid_request · 10000 · 400
ตรวจฟิลด์บังคับ รูปแบบ และเงื่อนไขช่องทาง แล้วแก้คำขอ
invalid_api_key · 11001 · 401
ตรวจ X-Api-Key และว่า workspace ยังใช้งานอยู่