ตัวฟัง Webhook ของ Microsoft Graph

ลองนึกภาพแบบนี้: แทนที่โทรศัพท์ของคุณจะต้องคอยเช็คตู้เย็นอยู่ตลอดว่านมหมดหรือยัง ตู้เย็นกลับส่งข้อความมาหาคุณทันทีที่นมหมด นั่นแหละคือสิ่งที่ webhook listener ทำ — มันคอยรอสัญญาณ แล้วก็ตอบสนองโดยอัตโนมัติ

---

จริง ๆ แล้วมันทำอะไร?

Microsoft Graph Webhook Listener คือฟีเจอร์หนึ่งใน Hermes Agent ที่ให้ Microsoft 365 (M365) บอก Hermes เมื่อมีบางอย่างเกิดขึ้น — เช่น การประชุม Teams จบลง มีข้อความแชทใหม่เข้า หรือมีอีเวนต์ในปฏิทินถูกอัปเดต

มันไม่ใช่แชทบอทที่คุณคุยด้วย มันเหมือนผู้ช่วยเงียบ ๆ ที่คอยฟัง “การแจ้งเตือนการเปลี่ยนแปลง” จาก Microsoft Graph แล้วก็ทริกเกอร์ pipeline เพื่อทำสิ่งที่มีประโยชน์ — เช่น ดึงบันทึกการประชุมแล้วโพสต์สรุปกลับไปใน Teams

---

สิ่งที่ต้องเตรียมก่อนเริ่ม

คุณต้องมีสามอย่าง:

1. ข้อมูลรับรองแอป Microsoft Graph — ลงทะเบียนแอปใน Azure portal ของ Microsoft
2. URL HTTPS สาธารณะ — Microsoft Graph จะไม่เรียกหา localhost dev tunnel ใช้ทดสอบได้ แต่โดเมนจริงดีที่สุดสำหรับโปรดักชัน
3. Secret ที่แข็งแรง — นี่คือค่า clientState ของคุณ ใช้เพื่อยืนยันว่าการแจ้งเตือนมาจาก Microsoft จริง ๆ

สร้าง secret ด้วยคำสั่ง:

openssl rand -hex 32

ใส่ลงใน ~/.hermes/.env แบบนี้:

MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here

---

การตั้งค่าเริ่มต้นอย่างรวดเร็ว

วิธีที่ง่ายที่สุดในการเปิดใช้งาน listener คือการใช้ไฟล์คอนฟิกขั้นต่ำ (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "replace-with-a-strong-secret"
      accepted_resources:
        - "communications/onlineMeetings"

หรือใช้ environment variables ใน ~/.hermes/.env (จะถูกผสานโดยอัตโนมัติเมื่อเริ่มระบบ):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

หมายเหตุ: bind host อ่านได้จาก extra.host ในไฟล์คอนฟิกเท่านั้น — ไม่มี env-var MSGRAPH_WEBHOOK_HOST ให้ใช้แทนได้

---

เริ่มต้น Listener

รันคำสั่งนี้เพื่อเริ่ม gateway:

hermes gateway run

เมื่อรันแล้ว listener จะเปิด endpoint เหล่านี้:

• POST /msgraph/webhook — รับการแจ้งเตือนการเปลี่ยนแปลงจาก Microsoft Graph
• GET /msgraph/webhook?validationToken=... — จัดการ handshake สำหรับการตรวจสอบการสมัครสมาชิก
• GET /health — readiness probe พร้อมตัวนับสำหรับการแจ้งเตือนที่ยอมรับ/ซ้ำซ้อน

---

ทำให้เป็นสาธารณะ

เพื่อให้ Microsoft Graph เข้าถึง listener ของคุณได้ คุณต้อง expose มันสู่สาธารณะ ใช้ reverse proxy, dev tunnel หรือ ingress ก็ได้ URL การแจ้งเตือนของคุณสำหรับ Graph subscriptions จะเป็น:

https://ops.example.com/msgraph/webhook

---

ตารางสรุปการตั้งค่า

การตั้งค่าทั้งหมดอยู่ภายใต้ platforms.msgraph_webhook.extra:

การตั้งค่า	ค่าเริ่มต้น	หน้าที่
host	ไม่ตั้งค่า (ทุกอินเทอร์เฟซ)	ที่อยู่สำหรับ bind ใช้ 127.0.0.1 สำหรับ dev tunnels
port	8646	พอร์ตที่ใช้ฟัง
webhook_path	/msgraph/webhook	Path ที่ Graph POST ข้อมูลมา
health_path	/health	Endpoint สำหรับ readiness
client_state	—	Secret ร่วมของคุณ ใช้เปรียบเทียบอย่างปลอดภัย
accepted_resources	[] (ยอมรับทั้งหมด)	รายการอนุญาตของเส้นทางทรัพยากร Graph ใช้ * สำหรับ wildcards

---

สรุป & เคล็ดลับการใช้งานจริง

Microsoft Graph Webhook Listener คือสะพานเชื่อมระหว่างอีเวนต์ M365 และการทำงานของ Hermes มันไม่ซับซ้อน — แค่ listener ที่คอยรอสัญญาณ แล้วก็ทริกเกอร์เวิร์กโฟลว์

เคล็ดลับ: เริ่มต้นด้วยการจำกัด accepted_resources ให้เหลือเพียงทรัพยากรเดียว (เช่น communications/onlineMeetings) เพื่อให้ง่ายก่อน พอเห็นการแจ้งเตือนไหลเข้ามาแล้ว ค่อยขยายรายการ และใช้ client_state ที่สร้างอย่างถูกต้องเสมอ — มันคือ handshake ด้านความปลอดภัยของคุณกับ Microsoft

---