Telegram Webhook secret_token เทียบกับ HMAC: ตัวรับต้องตรวจสอบอะไร

secret_token ของ Telegram Bot API ไม่ใช่ลายเซ็น HMAC เมื่อกำหนดผ่าน setWebhook แล้ว Telegram จะส่งค่าเดิมในเฮดเดอร์ X-Telegram-Bot-Api-Secret-Token ตัวรับต้องเปรียบเทียบค่านี้กับโทเคนที่ตั้งไว้ ส่วน webhook ของ UnifyPort ใช้กติกาอีกแบบ: เมื่อเปิดการลงลายเซ็น ต้องคำนวณ HMAC-SHA256 จาก timestamp และไบต์ดิบของเนื้อหาคำขอ แล้วตรวจสอบ X-Device-Signature การตรวจสอบสองแบบนี้ใช้แทนกันไม่ได้

ความแตกต่างที่ต้องรู้ก่อน

• เฮดเดอร์ของ Telegram ส่งข้อมูลลับที่ใช้ร่วมกันโดยตรง ไม่ใช่ digest ที่คำนวณจาก JSON
• ลายเซ็นของ UnifyPort ใช้ signing_secret ของ endpoint เพื่อผูกเนื้อหาดิบกับ X-Device-Timestamp
• ทั้งสองแบบยังต้องใช้ HTTPS ปกป้องข้อมูลลับ และประมวลผลซ้ำอย่างปลอดภัย
• เลือกวิธีตรวจสอบจากการตั้งค่า route ที่เชื่อถือได้ ไม่ใช่จากฟิลด์ provider ใน JSON ที่ยังไม่ผ่านการตรวจสอบ หรือจากเฮดเดอร์ใดก็ตามที่ส่งมา

บทความนี้เน้นการยืนยันคำขอ ไม่ใช่การเลือกตัวตนของบัญชี หากยังตัดสินใจระหว่างบอตกับบัญชีรับส่งข้อความเดิม ให้เริ่มจาก Telegram Bot API webhook เทียบกับ unified inbound webhook

secret_token ของ Telegram ตรวจสอบอะไรจริง ๆ

เอกสาร Telegram Bot API อย่างเป็นทางการ ระบุว่า secret_token เป็นพารามิเตอร์ทางเลือกของ setWebhook มีความยาว 1–256 อักขระ และใช้ได้เฉพาะ A-Z, a-z, 0-9, _ และ - เมื่อตั้งค่าแล้ว Telegram จะส่งค่านี้ใน X-Telegram-Bot-Api-Secret-Token กับทุกคำขอ webhook

หากตัวรับกำหนดให้ต้องมีการป้องกันนี้ คำขอที่ไม่มีเฮดเดอร์หรือมีค่าไม่ตรงกันต้องไม่เข้าสู่คิวที่เชื่อถือได้ ค่าที่ตรงกันแสดงว่าผู้ส่งมีโทเคนที่กำหนดไว้ แต่ไม่ได้สร้างความสัมพันธ์ทางการเข้ารหัสระหว่างโทเคนกับเนื้อหาคำขอ

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

แนะนำให้ใช้ข้อมูลลับเฉพาะสำหรับ webhook ไม่ใช้ bot token ซ้ำ และไม่วางข้อมูลลับในบริการเก็บคำขอสาธารณะ ควรปิดบังค่าใน access log ข้อมูล tracing ที่ส่งออก และภาพหน้าจอสำหรับแจ้งปัญหาด้วย

โทเคนคงที่กับลายเซ็นเนื้อหา

HMAC เป็นกลไกยืนยันข้อความด้วยคีย์ลับร่วมกัน ตามเอกสาร UnifyPort ตัวรับต้องคำนวณ digest ใหม่จากข้อมูลที่กำหนด ไม่ใช่เปรียบเทียบเฮดเดอร์ลายเซ็นกับคีย์ลับโดยตรง

ประเด็น	Telegram Bot API webhook	UnifyPort webhook ที่เปิดลายเซ็น
การตั้งค่า	setWebhook.secret_token	signing_secret ของ endpoint
เฮดเดอร์ที่ตรวจสอบ	X-Telegram-Bot-Api-Secret-Token	X-Device-Signature
ค่าที่ได้รับ	โทเคนที่ตั้งไว้โดยตรง	HMAC-SHA256 digest แบบเลขฐานสิบหก
ครอบคลุมเนื้อหาหรือไม่	ไม่	ครอบคลุมไบต์ดิบ
ครอบคลุม timestamp หรือไม่	ไม่	ครอบคลุม X-Device-Timestamp
งานของตัวรับ	เปรียบเทียบเฮดเดอร์กับโทเคน	คำนวณและเปรียบเทียบ digest
รับประกันว่าทำงานครั้งเดียวหรือไม่	ไม่	ไม่

ข้อมูลที่ UnifyPort ใช้ลงลายเซ็นต้องเป็นรูปแบบนี้อย่างเคร่งครัด:

<X-Device-Timestamp>.<raw request body>

timestamp ใช้รูปแบบ RFC 3339 UTC และมีจุดคั่นจริงหนึ่งตัว การจัดรูปแบบ JSON ใหม่ เปลี่ยนช่องว่าง หรือแปลงกลับเป็น JSON หลัง parse อาจเปลี่ยนไบต์ที่ใช้ลงลายเซ็น signing_secret คือคีย์ HMAC ไม่ใช่ค่าที่เฮดเดอร์ลายเซ็นต้องเท่ากับโดยตรง

หาก signing_secret ว่าง UnifyPort จะปิดการลงลายเซ็นและไม่ส่ง X-Device-Signature ตัวรับที่บังคับให้มีลายเซ็นควรปฏิเสธคำขอ ไม่เปลี่ยนวิธีตรวจสอบโดยอัตโนมัติ

แยกเส้นทางรับข้อมูลสองแบบ

แนวทางที่แนะนำคือใช้ route ของแอปแยกกันสำหรับ Telegram update แบบดั้งเดิมกับ UnifyPort event นี่เป็นข้อเสนอด้านการออกแบบแอป ไม่ใช่ endpoint ใหม่ของผู้ให้บริการ แม้จะรวม LINE และ Telegram ไว้ในคิวบริการลูกค้าเดียวกัน ก็ควรตรวจสอบแต่ละทางเข้าก่อนรวมงาน

1. ผูก route กับผู้ส่งและข้อมูลลับ กำหนดวิธีตรวจสอบในการตั้งค่าระบบก่อนรับทราฟฟิก
2. ยืนยันคำขอก่อนส่งต่องาน Telegram ตรวจเฮดเดอร์โทเคน ส่วน UnifyPort ที่เปิดลายเซ็นตรวจ HMAC ของเนื้อหาดิบและความใหม่ของ timestamp
3. ตรวจโครงสร้างข้อมูลให้ตรงประเภท อย่าส่ง Telegram Update ให้ตัวประมวลผลที่คาดว่าจะได้รับ UnifyPort message.received
4. บันทึกงานที่รับแล้วอย่างถาวร แยกการยืนยันคำขอ การป้องกันงานซ้ำ และการตรวจสิทธิ์ทางธุรกิจออกจากกัน
5. บันทึกชนิดของข้อผิดพลาด ไม่ใช่ข้อมูลลับ log ควรบอกว่าการตรวจสอบใดล้มเหลวโดยไม่เปิดเผยค่าโทเคน

หลีกเลี่ยง middleware แบบ “เฮดเดอร์ใดผ่านก็ยอมรับ” บน route เดียว เพราะสาขาที่อ่อนกว่าหรือเปิดไว้โดยไม่ตั้งใจจะกลายเป็นทางเลือกแทนกติกาที่ต้องการ โดยเฉพาะอย่าใช้โทเคน Telegram แทน HMAC ที่ route ของ UnifyPort กำหนดให้ต้องมี

ดูรายละเอียดของกติกาแบบที่สองใน คู่มือ HMAC การป้องกัน replay และการรับคำขอซ้ำ เวลาที่อยู่ใน JSON ของข้อความไม่ใช่ตัวแทนของ timestamp ที่ได้รับการปกป้องด้วยลายเซ็นการส่ง

ทดสอบขอบเขตก่อนใช้งานจริง

ตารางนี้เป็นข้อเสนอการทดสอบ ไม่ใช่ผลการทดสอบที่ดำเนินการแล้ว ใช้ข้อมูลลับที่คุณควบคุมในสภาพแวดล้อมแยกต่างหาก

การทดสอบ	พฤติกรรมที่คาดหวัง
เฮดเดอร์ Telegram หายหรือไม่ถูกต้อง	ปฏิเสธก่อนเข้าสู่การประมวลผลที่เชื่อถือได้
โทเคน Telegram ถูกต้องแต่เนื้อหาเปลี่ยน	ตรวจโทเคนอย่างเดียวไม่พบการเปลี่ยน ต้องมีการตรวจข้อมูลและขอบเขตการส่งที่เชื่อถือได้
เนื้อหา UnifyPort เปลี่ยนหลังลงลายเซ็น	ปฏิเสธเพราะ digest ไม่ตรง
ลายเซ็น UnifyPort ถูกต้อง แต่เวลาอยู่นอกช่วงที่ตั้งไว้	ปฏิเสธตามนโยบายความใหม่
ส่งโทเคน Telegram ไปยัง route ของ UnifyPort	ปฏิเสธโดยไม่สลับวิธีตรวจสอบ
event ปกติที่ถูกต้องถูกส่งมาอีกครั้ง	รับแบบ idempotent โดยไม่ทำงานธุรกิจซ้ำ

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

UnifyPort เหมาะกับส่วนไหน และไม่รับประกันอะไร

อินเทอร์เฟซที่ไม่เป็นทางการของ UnifyPort ส่ง event ในรูปแบบมาตรฐานจากบัญชีรับส่งข้อความที่เชื่อมต่อไว้ HMAC ปกป้องช่วง UnifyPort ส่งข้อมูลมายังตัวรับของคุณ ไม่ใช่ลายเซ็นดั้งเดิมของ Telegram และไม่ใช่หลักฐานยืนยันผู้เขียน Telegram แบบต้นทางถึงปลายทาง

หากผลิตภัณฑ์เป็นบอต Telegram อยู่แล้ว ให้ใช้การป้องกันตามเอกสาร Telegram ในทางเข้านั้น ไม่จำเป็นต้องเปลี่ยนแพลตฟอร์มเพียงเพื่อเปลี่ยนวิธีตรวจสอบ หากใช้ UnifyPort ทำคิวระดับบัญชีหรือหลายช่องทาง ให้ใช้กติกาของ UnifyPort และเปิดลายเซ็นตอนสร้าง webhook endpoint

คำถามที่พบบ่อย

ต้องใช้ Telegram secret_token คำนวณ HMAC หรือไม่?

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

เปรียบเทียบ X-Device-Signature กับ signing_secret โดยตรงได้ไหม?

ไม่ได้ ต้องคำนวณ HMAC-SHA256 จาก timestamp และเนื้อหาดิบตามเอกสาร แล้วเปรียบเทียบ digest กับลายเซ็นเลขฐานสิบหกที่ได้รับ

วิธีใดวิธีหนึ่งป้องกันการทำงานซ้ำได้ไหม?

ไม่ได้ การยืนยันคำขอและการจัดการข้อมูลซ้ำเป็นคนละเรื่อง ต้องบันทึกงานที่รับแล้วและทำให้การทำงานปลายทางเป็น idempotent ลายเซ็น HMAC อย่างเดียวไม่รับประกันการส่งเพียงครั้งเดียว

ขั้นตอนถัดไปและแหล่งข้อมูล

ใช้ เอกสารการส่ง webhook และการตรวจลายเซ็น เป็นข้อกำหนดสำหรับพัฒนาตัวรับ UnifyPort

ตรวจสอบแหล่งข้อมูลเมื่อ 2026-09-17:

• Telegram Bot API: setWebhook และ secret_token
• RFC Editor: HMAC, RFC 2104
• การส่ง webhook ของ UnifyPort
• การสร้าง endpoint ของ UnifyPort