Microsoft Graph Webhook Listener | Easy Understand Hermes Agent

이렇게 생각해 보세요. 냉장고에 우유가 떨어졌는지 휴대폰으로 계속 확인하는 대신, 우유가 떨어지는 순간 냉장고가 직접 문자를 보내주는 거예요. 바로 그게 웹훅 리스너가 하는 일입니다 — 신호를 기다렸다가 자동으로 반응하는 거죠.

이게 실제로 뭘 하는 건가요?

Microsoft Graph Webhook Listener는 Hermes Agent의 기능 중 하나로, Microsoft 365(M365)에서 무언가 이벤트가 발생했을 때 — 예를 들어 Teams 회의가 끝나거나, 새 채팅 메시지가 오거나, 일정 이벤트가 업데이트되는 경우 — Hermes에게 알려주는 역할을 합니다.

말을 거는 챗봇이 아니라, Microsoft Graph의 “변경 알림(change notifications)“을 조용히 듣고 있다가 유용한 작업을 수행하는 파이프라인을 실행하는 조용한 비서에 가깝습니다. 예를 들어 회의 녹취록을 가져와서 Teams에 요약을 다시 게시하는 식이죠.

시작 전에 필요한 것들

세 가지가 필요합니다:

Microsoft Graph 앱 자격 증명 — Microsoft Azure 포털에서 앱을 등록하세요.
공개 HTTPS URL — Microsoft Graph는 localhost를 호출하지 않습니다. 테스트에는 dev tunnel이 유용하고, 프로덕션에는 실제 도메인이 가장 좋습니다.
강력한 시크릿(secret) — 이 값은 clientState로 사용되며, 알림이 진짜 Microsoft에서 왔는지 확인하는 데 쓰입니다.

시크릿은 다음과 같이 생성하세요:

openssl rand -hex 32

그리고 ~/.hermes/.env 파일에 이렇게 넣어주세요:

MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here

빠른 시작 설정

리스너를 활성화하는 가장 간단한 방법은 최소한의 설정 파일(~/.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"

또는 ~/.hermes/.env 파일에서 환경 변수를 사용할 수도 있습니다 (시작 시 자동으로 병합됩니다):

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

참고: 바인드 호스트는 설정 파일의 extra.host에서만 읽습니다. MSGRAPH_WEBHOOK_HOST 환경 변수로는 덮어쓸 수 없습니다.

리스너 시작하기

게이트웨이를 시작하려면 다음 명령어를 실행하세요:

hermes gateway run

실행이 시작되면 리스너는 다음 엔드포인트를 노출합니다:

POST /msgraph/webhook — Microsoft Graph의 변경 알림을 수신합니다
GET /msgraph/webhook?validationToken=... — 구독 검증 핸드셰이크를 처리합니다
GET /health — 수락/중복 알림 카운터가 포함된 준비 상태(readiness) 프로브입니다

공개적으로 노출하기

Microsoft Graph가 리스너에 도달하려면 공개적으로 노출해야 합니다. 리버스 프록시, dev tunnel 또는 인그레스를 사용하세요. Graph 구독의 알림 URL은 다음과 같습니다:

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

설정 치트 시트

모든 설정은 platforms.msgraph_webhook.extra 아래에 있습니다:

설정	기본값	설명
`host`	설정 안 됨 (모든 인터페이스)	바인드 주소. dev tunnel에는 `127.0.0.1`을 사용하세요.
`port`	`8646`	수신 대기 포트.
`webhook_path`	`/msgraph/webhook`	Graph가 POST를 보내는 경로.
`health_path`	`/health`	준비 상태 엔드포인트.
`client_state`	—	공유 시크릿. 안전하게 비교됩니다.
`accepted_resources`	`[]` (모두 수락)	Graph 리소스 경로의 허용 목록. 와일드카드에는 `*`를 사용하세요.

요약 및 실용적인 팁

Microsoft Graph Webhook Listener는 M365 이벤트와 Hermes 작업 사이의 다리 역할을 합니다. 복잡하지 않습니다 — 신호를 기다렸다가 워크플로우를 실행하는 리스너일 뿐이죠.

실용적인 팁: 처음에는 accepted_resources를 하나의 리소스(예: communications/onlineMeetings)로 제한해서 단순하게 유지하세요. 알림이 흐르는 것을 확인한 후에 목록을 확장하세요. 그리고 항상 제대로 생성된 client_state를 사용하세요 — 그것이 Microsoft와의 보안 핸드셰이크입니다.