Webhook

เมื่อมีเหตุการณ์ที่เกี่ยวกับบอท HeloSChat จะส่ง POST แบบ JSON ไปที่ Webhook URL ของคุณ ตอบ 2xx ภายใน 10 วินาทีเพื่อยืนยันว่าได้รับแล้ว

รูปแบบที่ได้รับ

{
  "bid": "4f1c…",
  "bot_id": "4f1c…",
  "webhook_event_id": "9b2e7c1a-…",
  "delivery_context": { "is_redelivery": false, "retry_count": 0 },
  "event": {
    "type": "message.create",
    "channel_type": "dm",
    "channel_id": "…",
    "message_id": "…",
    "content": "เช็คสถานะคำสั่งซื้อ",
    "attachments": [],
    "author": { "id": "…", "uid": "U12AB34CD", "username": "mint", "display_name": "Mint" },
    "reply_token": "rt_…",
    "created_at": "2026-10-07T13:00:00Z"
  }
}

ตรวจลายเซ็น

ทุก request มี header X-Helos-Bot-Signature เป็น sha256= ตามด้วย HMAC-SHA256 (hex) ของ body ดิบ โดยใช้ Webhook secret ของบอท เป็นกุญแจ ดู secret และออกใหม่ได้ในแท็บ Webhook ของ Console

const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)            // Buffer ของ body ก่อน parse
  .digest("hex");
const got = req.get("X-Helos-Bot-Signature") || "";
const ok = got.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));

การส่งซ้ำ

ถ้าเซิร์ฟเวอร์ของคุณไม่ตอบ 2xx หรือติดต่อไม่ได้ ระบบจะส่ง event เดิมซ้ำอีก 5 ครั้ง ห่างกัน 10 วินาที, 1 นาที, 5 นาที, 30 นาที และ 2 ชั่วโมง หลังจากนั้นจะถือว่าล้มเหลว คุณกดส่งซ้ำเองได้จากประวัติใน Console

• webhook_event_id เหมือนเดิมทุกครั้งที่ส่งซ้ำ ใช้กันการประมวลผลซ้ำ
• delivery_context.is_redelivery เป็น true เมื่อเป็นการส่งซ้ำ
• reply token ของ event ที่ส่งซ้ำจะได้อายุใหม่ ถ้ายังไม่เคยถูกใช้

ประเภท event

event ของกลุ่มและเซิร์ฟเวอร์ส่งให้เฉพาะบอทที่ได้รับอนุมัติสิทธิ์พื้นที่นั้นแล้ว ส่วน event ของห้องที่บอทไม่มีสิทธิ์จะถูกกรองทิ้ง

เพื่อนและสมาชิก

follow ส่งมาพร้อม channel_id ของแชทส่วนตัว ใช้ reply token ทักทายผู้ใช้ได้ทันที ส่วน join และ member.joined ส่ง channel_id ของห้องข้อความห้องแรกในกลุ่มหรือเซิร์ฟเวอร์

{
  "type": "follow",
  "channel_type": "dm",
  "channel_id": "8f0c…",
  "reply_token": "rt_…",
  "user": { "id": "3b1e…", "uid": "HELOS123", "username": "somchai", "display_name": "สมชาย" },
  "created_at": "2026-10-07T06:30:00Z"
}

• unfollow, leave และ member.left ไม่มี reply token เพราะไม่มีใครให้ตอบแล้ว
• การบล็อกบอทนับเป็น unfollow
• บอทไม่ได้รับ event เมื่อกลุ่มหรือเซิร์ฟเวอร์ถูกลบทั้งหมด

ข้อกำหนดของ URL

• ต้องเป็น HTTPS
• ต้องไม่ชี้ไปที่ที่อยู่ภายในเครือข่ายหรือ localhost
• ตอบภายใน 10 วินาที งานที่ใช้เวลานานให้ทำหลังตอบ 200 แล้ว