Webhook API

endpoint ในหน้านี้ใช้ดู ตั้ง ลบ และทดสอบ webhook ของบอท ส่วนรูปแบบ event และการตรวจลายเซ็นอยู่ที่หน้า Webhook

ดู webhook

GET /v1/me/webhook

{ "url": "https://bot.example.com/sukson", "secret_hint": "Xy9Q", "consecutive_failures": 0 }

ฟิลด์	คำอธิบาย
url	URL ปัจจุบัน หรือ null ถ้ายังไม่ได้ตั้ง
secret_hint	4 ตัวท้ายของรหัสลับ ใช้เช็กว่าเซิร์ฟเวอร์ของคุณใช้รหัสลับตัวไหนอยู่
consecutive_failures	จำนวนครั้งที่ส่งล้มเหลวติดกัน (ถึงเกณฑ์แล้วบอทหยุดเอง ดู การส่งซ้ำ)

ตั้ง webhook

PUT /v1/me/webhook

curl -s -X PUT https://api.sukson.dev/v1/me/webhook \
  -H "Authorization: Bearer $SUKSON_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.com/sukson"}'

1. ระบบตรวจ เงื่อนไขของ URL
2. ส่ง event ping ที่ลงลายเซ็นด้วยรหัสลับใหม่ เซิร์ฟเวอร์ต้องตอบ 2xx ภายใน 10 วินาที
3. บันทึก URL แล้วตอบรหัสลับใหม่

{ "url": "https://bot.example.com/sukson", "secret": "kX2…(43 ตัว)…Xy9Q", "secret_hint": "Xy9Q" }

• secret แสดงครั้งเดียว และมาเฉพาะเมื่อ URL เปลี่ยน ถ้าตั้ง URL เดิมซ้ำ secret เป็น null และรหัสลับเดิมใช้ต่อ
• รหัสลับใหม่ทำให้ sender.id ของทุกคนเปลี่ยน ถ้าคุณเก็บข้อมูลผูกกับ sender.id ไว้ ให้วางแผนก่อนเปลี่ยน URL
• โค้ดที่ตรวจลายเซ็นต้องรู้จักรหัสลับใหม่ก่อน ping มาถึง วิธีที่ปลอดภัยคือให้เซิร์ฟเวอร์รับได้ทั้งรหัสลับใหม่และรหัสเดิมไปสักพัก

HTTP	code	เมื่อไร
422	INVALID_WEBHOOK_URL	URL ใช้ไม่ได้ details.reason เป็น invalid_url, not_https, credentials_in_url, port_not_allowed, ip_address_host หรือ internal_host
422	INVALID	ไม่มี url หรือยาวเกิน 2,048 ตัวอักษร
422	INVALID	ping ไม่ผ่าน (เซิร์ฟเวอร์ไม่ตอบ 2xx ภายใน 10 วินาที) details.reason เป็น ping_failed URL เดิมยังใช้ต่อ

ลบ webhook

DELETE /v1/me/webhook

เลิกใช้ webhook บอทจะไม่ได้รับ event จนกว่าจะตั้ง URL ใหม่ แต่ยังส่งข้อความแบบ push ได้ตามปกติ

{ "url": null }

ทดสอบ webhook

POST /v1/me/webhook/test

ส่ง ping ที่ลงลายเซ็นไปที่ URL ปัจจุบัน ไม่ต้องมี body (หรือส่ง {})

{ "ok": true, "status_category": "http_200", "latency_ms": 184 }

ฟิลด์	คำอธิบาย
ok	true เมื่อเซิร์ฟเวอร์ตอบ 2xx
status_category	http_<status> เมื่อเซิร์ฟเวอร์ตอบ หรือหมวดความล้มเหลว เช่น timeout, connect_failed, blocked_address, response_too_large ระบบไม่ส่งเนื้อหาที่เซิร์ฟเวอร์ตอบกลับมาให้
latency_ms	เวลาที่ใช้ (มิลลิวินาที)

บอทที่ยังไม่ได้ตั้ง webhook ได้ 422 INVALID พร้อม details.reason เป็น no_webhook