Pendengar Webhook Microsoft Graph

Bayangkan begini: alih-alih kamu terus-menerus mengecek kulkas untuk melihat apakah susu sudah habis, kulkas itu malah mengirimimu pesan begitu susunya habis. Persis seperti itulah cara kerja webhook listener — ia menunggu sinyal, lalu bereaksi secara otomatis.

---

Sebenarnya Apa yang Dilakukan Fitur Ini?

Microsoft Graph Webhook Listener adalah fitur di Hermes Agent yang memungkinkan Microsoft 365 (M365) memberi tahu Hermes ketika sesuatu terjadi — seperti rapat Teams yang berakhir, pesan chat baru yang masuk, atau event kalender yang diperbarui.

Ini bukan chatbot yang bisa kamu ajak ngobrol. Ini lebih seperti asisten senyap yang mendengarkan “notifikasi perubahan” dari Microsoft Graph, lalu memicu pipeline untuk melakukan sesuatu yang berguna — seperti mengambil transkrip rapat dan mengirimkan ringkasannya kembali ke Teams.

---

Yang Kamu Butuhkan Sebelum Memulai

Kamu perlu tiga hal:

1. Kredensial aplikasi Microsoft Graph — daftarkan aplikasi di portal Azure milik Microsoft.
2. URL HTTPS publik — Microsoft Graph tidak akan memanggil localhost. Tunnel pengembangan (dev tunnel) bisa dipakai untuk pengujian; domain asli paling baik untuk produksi.
3. Secret yang kuat — ini adalah nilai clientState milikmu, digunakan untuk memverifikasi bahwa notifikasi benar-benar berasal dari Microsoft.

Buat secret dengan perintah:

openssl rand -hex 32

Simpan di ~/.hermes/.env seperti ini:

MSGRAPH_WEBHOOK_CLIENT_STATE=secret-generatemu-di-sini

---

Pengaturan Awal Cepat

Cara paling sederhana untuk mengaktifkan listener adalah dengan file konfigurasi minimal (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "ganti-dengan-secret-yang-kuat"
      accepted_resources:
        - "communications/onlineMeetings"

Atau gunakan variabel lingkungan di ~/.hermes/.env (ini akan otomatis digabungkan saat startup):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=secret-generatemu-di-sini
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Catatan: Host pengikat (bind host) hanya dibaca dari extra.host di file konfigurasi — tidak ada penggantian via env-var MSGRAPH_WEBHOOK_HOST.

---

Memulai Listener

Jalankan perintah ini untuk memulai gateway:

hermes gateway run

Setelah berjalan, listener akan menyediakan endpoint-endpoint berikut:

• POST /msgraph/webhook — menerima notifikasi perubahan dari Microsoft Graph
• GET /msgraph/webhook?validationToken=... — menangani proses jabat tangan validasi langganan (subscription)
• GET /health — probe kesiapan dengan penghitung untuk notifikasi yang diterima/duplikat

---

Membuatnya Bisa Diakses Publik

Agar Microsoft Graph bisa menjangkau listener-mu, kamu perlu mengeksposnya ke publik. Gunakan reverse proxy, dev tunnel, atau ingress. URL notifikasi untuk langganan Graph akan menjadi:

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

---

Lembar Cheat Konfigurasi

Semua pengaturan berada di bawah platforms.msgraph_webhook.extra:

Pengaturan	Default	Fungsinya
host	tidak diatur (semua antarmuka)	Alamat bind. Gunakan 127.0.0.1 untuk dev tunnel.
port	8646	Port yang digunakan untuk mendengarkan.
webhook_path	/msgraph/webhook	Jalur tempat Graph mengirim POST.
health_path	/health	Endpoint kesiapan.
client_state	—	Secret bersama milikmu, dibandingkan secara aman.
accepted_resources	[] (terima semua)	Daftar izin jalur resource Graph. Gunakan * untuk wildcard.

---

Ringkasan & Tips Praktis

Microsoft Graph Webhook Listener adalah jembatan antara event M365 dan aksi Hermes. Ini tidak rumit — hanya sebuah listener yang menunggu sinyal, lalu memicu alur kerja.

Tips praktis: Mulailah dengan accepted_resources yang dibatasi hanya satu resource (seperti communications/onlineMeetings) agar semuanya tetap sederhana. Setelah kamu melihat notifikasi mengalir, perluas daftarnya. Dan selalu gunakan client_state yang dibuat dengan benar — itu adalah jabat tangan keamananmu dengan Microsoft.

---