Trình lắng nghe Webhook Microsoft Graph | Easy Understand Hermes Agent

Hãy hình dung thế này: thay vì bạn phải liên tục kiểm tra tủ lạnh xem sữa còn hay hết, thì cái tủ lạnh sẽ tự động nhắn tin cho bạn ngay khi sữa vừa hết. Đó chính xác là những gì một webhook listener làm — nó chờ một tín hiệu, rồi tự động phản ứng.

Thực Chất Công Cụ Này Làm Gì?

Microsoft Graph Webhook Listener là một tính năng trong Hermes Agent, cho phép Microsoft 365 (M365) báo cho Hermes biết khi có sự kiện xảy ra — như một cuộc họp Teams kết thúc, có tin nhắn mới, hay một sự kiện trên lịch được cập nhật.

Nó không phải là một chatbot để bạn trò chuyện. Nó giống như một trợ lý thầm lặng, lắng nghe các “thông báo thay đổi” từ Microsoft Graph, sau đó kích hoạt một pipeline để làm việc gì đó hữu ích — ví dụ như lấy biên bản cuộc họp và đăng tóm tắt trở lại kênh Teams.

Những Gì Bạn Cần Chuẩn Bị Trước Khi Bắt Đầu

Bạn cần ba thứ:

Thông tin đăng nhập ứng dụng Microsoft Graph — đăng ký một ứng dụng trong cổng Azure của Microsoft.
Một URL HTTPS công khai — Microsoft Graph sẽ không gọi tới localhost. Một dev tunnel có thể dùng để kiểm thử; một tên miền thật là tốt nhất cho môi trường production.
Một chuỗi bí mật mạnh — đây là giá trị clientState của bạn, dùng để xác minh rằng các thông báo thực sự đến từ Microsoft.

Tạo một chuỗi bí mật bằng lệnh:

openssl rand -hex 32

Đặt nó vào file ~/.hermes/.env như sau:

MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here

Thiết Lập Nhanh

Cách đơn giản nhất để kích hoạt listener là dùng một file cấu hình tối giản (~/.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"

Hoặc dùng các biến môi trường trong file ~/.hermes/.env (các biến này sẽ được tự động gộp khi khởi động):

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

Lưu ý: Địa chỉ bind host chỉ được đọc từ extra.host trong file cấu hình — không có biến môi trường MSGRAPH_WEBHOOK_HOST nào để ghi đè.

Khởi Động Listener

Chạy lệnh sau để khởi động gateway:

hermes gateway run

Sau khi chạy, listener sẽ mở các endpoint sau:

POST /msgraph/webhook — nhận thông báo thay đổi từ Microsoft Graph
GET /msgraph/webhook?validationToken=... — xử lý bắt tay xác thực subscription
GET /health — một endpoint kiểm tra sẵn sàng với các bộ đếm cho thông báo được chấp nhận/trùng lặp

Đưa Listener Ra Công Khai

Để Microsoft Graph có thể truy cập listener của bạn, bạn cần phải phơi bày nó ra công khai. Hãy dùng reverse proxy, dev tunnel, hoặc ingress. URL thông báo cho các subscription Graph của bạn sẽ là:

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

Bảng Cấu Hình Tham Khảo Nhanh

Tất cả các thiết lập nằm dưới platforms.msgraph_webhook.extra:

Cài đặt	Mặc định	Chức năng
`host`	không đặt (tất cả các interface)	Địa chỉ bind. Dùng `127.0.0.1` cho dev tunnels.
`port`	`8646`	Cổng lắng nghe.
`webhook_path`	`/msgraph/webhook`	Đường dẫn Graph POST tới.
`health_path`	`/health`	Endpoint kiểm tra sẵn sàng.
`client_state`	—	Chuỗi bí mật dùng chung của bạn, được so sánh một cách an toàn.
`accepted_resources`	`[]` (chấp nhận tất cả)	Danh sách cho phép các đường dẫn tài nguyên Graph. Dùng `*` cho ký tự đại diện.

Tổng Kết & Mẹo Thực Tế

Microsoft Graph Webhook Listener là cầu nối giữa các sự kiện M365 và các hành động của Hermes. Nó không hề phức tạp — chỉ là một listener chờ tín hiệu, rồi kích hoạt một quy trình làm việc.

Mẹo thực tế: Bắt đầu với accepted_resources giới hạn ở một tài nguyên (như communications/onlineMeetings) để giữ mọi thứ đơn giản. Khi bạn đã thấy các thông báo chạy, hãy mở rộng danh sách. Và luôn dùng một client_state được tạo đúng cách — đó là cái bắt tay bảo mật của bạn với Microsoft.