Cara Membangun Webhook Microsoft Graph yang Andal untuk SharePoint dan M365

By Mirko Peters · 2025-11-16

Bangun webhook Microsoft Graph yang andal untuk SharePoint dan M365 dengan validasi aman, perpanjangan otomatis, dan pengiriman notifikasi yang tangguh.

Automatically translated with AI from the original post. Read the English original

Membangun webhook Microsoft Graph yang andal untuk SharePoint dan M365 bisa menjadi tantangan, bahkan bagi pengembang berpengalaman. Anda mungkin menemui masalah seperti kegagalan validasi jika endpoint Anda tidak mengembalikan token validasi atau tidak merespons dengan status 200 OK. Masalah umum meliputi endpoint yang diblokir firewall, salah konfigurasi jaringan, atau gangguan dari middleware. Percobaan ulang yang terlewat dan langganan yang kedaluwarsa sering terjadi ketika layanan tidak menerima permintaan validasi atau ketika endpoint tidak dapat diakses secara publik. Anda akan mempelajari cara menghindari jebakan tersebut dan membangun jalur notifikasi yang tangguh dan aman, lengkap dengan daftar periksa praktis serta praktik terbaik.

Poin Penting

• Webhook Microsoft Graph menyediakan notifikasi real-time tentang perubahan di Microsoft 365, sehingga tidak perlu lagi melakukan polling terus-menerus.

• Pastikan endpoint webhook Anda dapat diakses secara publik dan menggunakan HTTPS untuk menjaga keamanan serta keandalan.

• Tanggapi permintaan validasi dengan cepat dengan mengembalikan token validasi agar langganan webhook Anda berhasil diaktifkan.

• Terapkan strategi percobaan ulang dan backoff yang tangguh untuk menangani kegagalan pengiriman notifikasi dan mencegah kehilangan data.

• Otomatiskan perpanjangan langganan dan pantau jalur webhook Anda untuk memastikan notifikasi yang berkelanjutan dan andal.

Dasar-Dasar Webhook Microsoft Graph

Apa Itu Webhook Microsoft Graph

Webhook adalah permintaan HTTP yang dipicu oleh suatu peristiwa di sistem sumber dan dikirim ke sistem tujuan, sering kali disertai muatan data. Webhook bersifat otomatis, dengan kata lain, webhook dikirim secara otomatis saat peristiwanya terjadi di sistem sumber.

Anda menggunakan webhook Microsoft Graph untuk menerima notifikasi real-time tentang perubahan di lingkungan Microsoft 365 Anda. Artinya, Anda tidak perlu terus-menerus melakukan polling ke Microsoft Graph untuk mencari pembaruan. Sebaliknya, aplikasi Anda akan diberi tahu segera setelah sesuatu yang penting terjadi. Dengan cara ini, data Anda tetap mutakhir dan tersinkronisasi dengan data yang dapat diakses melalui Microsoft Graph. Cara ini juga menghilangkan kebutuhan akan infrastruktur polling, yaitu ketika Anda sering mengirim permintaan ke Microsoft Graph untuk memeriksa perubahan terbaru.

Anda dapat mengatur notifikasi untuk berbagai jenis peristiwa, misalnya:

• Pesan

• Acara

• Kontak

• Pengguna

• Grup

• Percakapan

• File OneDrive

• Peringatan

Misalnya, Anda mungkin ingin secara otomatis membuat akun di sistem pencatatan waktu pihak ketiga ketika pengguna baru bergabung dengan organisasi Anda. Anda juga dapat memicu pemrosesan konten, misalnya pelaporan biaya, ketika seseorang menambahkan file baru ke pustaka dokumen SharePoint atau folder OneDrive.

Mengapa Keandalan Itu Penting

Webhook Microsoft Graph berperan penting dalam menjaga integrasi SharePoint dan Microsoft 365 Anda tetap responsif dan mutakhir. Ketika jalur webhook Anda bekerja dengan andal, aplikasi Anda merespons perubahan secara real-time. Pengguna selalu melihat data terkini, yang meningkatkan pengalaman mereka dan mengurangi risiko informasi yang usang.

Namun, masalah keandalan dapat menimbulkan dampak serius:

• Kegagalan webhook dapat membahayakan fungsi aplikasi jika tidak ditangani dengan benar.

• Lonjakan lalu lintas yang tiba-tiba dapat membebani server, menyebabkan downtime dan hilangnya permintaan webhook.

• Kegagalan dalam memproses webhook dapat mengakibatkan kehilangan dan ketidakkonsistenan data jika tidak ada mekanisme pengiriman ulang.

• URL webhook yang tidak diamankan dapat dieksploitasi, sehingga penyerang dapat mengirimkan data yang rusak.

Untuk membangun solusi yang tangguh, Anda sebaiknya menggabungkan webhook dengan delta query untuk melacak perubahan secara efisien. Anda juga perlu menyiapkan proses untuk memeriksa dan memperpanjang langganan secara berkala. Untuk sumber daya yang sering diperbarui, pengelompokan permintaan (batching) membantu mengelola beban.

Menyiapkan dan Memvalidasi Webhook

Menyiapkan Microsoft Graph Webhooks untuk SharePoint dan M365 melibatkan beberapa langkah penting. Anda perlu mendaftarkan webhook, menangani permintaan validasi, dan mengamankan endpoint Anda. Setiap langkah berperan penting untuk memastikan pipeline notifikasi Anda berjalan andal dan aman.

Mendaftarkan Microsoft Graph Webhooks

Anda memulai dengan membuat langganan webhook. Proses ini memungkinkan aplikasi Anda menerima notifikasi tentang perubahan pada sumber daya Microsoft 365. Ikuti langkah-langkah berikut untuk mendaftarkan webhook Anda:

1. Buat endpoint yang dapat diakses publik dengan menggunakan HTTPS. Endpoint ini akan menerima notifikasi dari Microsoft Graph.

2. Kirim permintaan POST ke endpoint /subscriptions di Microsoft Graph.

3. Dalam permintaan langganan Anda, tentukan:

   • changeType: Jenis perubahan yang ingin Anda lacak, misalnya "created", "updated", atau "deleted".

   • notificationUrl: URL endpoint webhook Anda.

   • resource: Sumber daya yang ingin Anda pantau, misalnya "/users" atau "/drive/root".

   • expirationDateTime: Tanggal dan waktu saat langganan harus berakhir.

   • Properti opsional, seperti clientState, membantu Anda memverifikasi sumber notifikasi.

Contoh permintaan langganan:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://yourdomain.com/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

Pastikan endpoint Anda dapat diakses publik dan diamankan dengan HTTPS. Microsoft Graph memvalidasi URL notifikasi sebelum menyelesaikan langganan. Anda perlu memperbarui langganan secara berkala agar tetap menerima notifikasi. Endpoint Anda harus memberikan respons HTTP yang tepat waktu dan konsisten agar tidak ada notifikasi yang terlewat.

Berikut ringkasan kolom yang wajib diisi untuk pendaftaran:

Menangani Permintaan Validasi

Setelah Anda mendaftarkan webhook, Microsoft Graph mengirimkan permintaan validasi ke endpoint Anda. Anda harus merespons dengan benar agar proses langganan selesai. Ketika endpoint Anda menerima permintaan GET dengan parameter kueri validationToken, Anda perlu menggemakan token tersebut dalam isi respons sebagai teks biasa dan mengembalikan status 200 OK.

• Jika validationToken tidak dikembalikan, akan terjadi kesalahan validasi. Artinya, Microsoft Graph tidak dapat mengonfirmasi endpoint Anda, dan Anda tidak akan menerima notifikasi.

• Anda sebaiknya menggunakan properti clientState untuk memastikan permintaan berasal dari langganan Anda.

• Selalu kembalikan validationToken dalam isi respons sebagai teks biasa dalam waktu 10 detik.

💡 Tips: Merespons permintaan validasi dengan cepat dan tepat memastikan langganan webhook Anda aktif tanpa kendala.

HTTPS dan Keamanan Endpoint

Mengamankan endpoint webhook Anda sangat penting. Microsoft Graph Webhooks memerlukan enkripsi HTTPS untuk melindungi data sensitif selama komunikasi. Anda sebaiknya memverifikasi permintaan masuk dengan memeriksa tanda tangan yang dibuat menggunakan kunci rahasia bersama. Gunakan jalur yang kompleks dan dibuat secara acak untuk URL callback Anda agar lebih sulit ditebak.

• Tambahkan daftar putih IP untuk endpoint API Microsoft Graph.

• Sertakan token autentikasi dalam header permintaan.

• Pantau penggunaan API Anda untuk mendeteksi pola yang tidak biasa atau lonjakan aktivitas.

• Batasi akses ke API Microsoft Graph dan Outlook. Hanya personel yang berwenang yang boleh memiliki akses, dan Anda harus menerapkan autentikasi multifaktor.

• Terapkan solusi keamanan endpoint tingkat lanjut yang menggunakan analitik perilaku dan pembelajaran mesin untuk mengidentifikasi ancaman.

• Lakukan audit keamanan secara rutin untuk menemukan dan memperbaiki kerentanan.

Setiap callback webhook menggunakan JSON Web Token (JWT) yang ditandatangani pada header Authentication dari permintaan HTTPS yang masuk. Anda dapat menggunakan teknik validasi JWT OpenID Connect standar untuk memastikan integritas token.

Anda wajib menggunakan HTTPS untuk semua endpoint webhook. Persyaratan ini melindungi data Anda dan memastikan kepatuhan terhadap standar keamanan Microsoft. Mengamankan endpoint Anda membantu mencegah akses tidak sah dan serangan.

Dengan mengikuti langkah-langkah ini, Anda menyiapkan pipeline Microsoft Graph Webhooks yang andal dan aman untuk SharePoint dan M365. Anda memastikan aplikasi menerima notifikasi dengan cepat dan aman.

Memproses dan Mengamankan Notifikasi

Setelah Anda menyiapkan endpoint webhook, Anda perlu memproses notifikasi yang masuk secara aman dan andal. Langkah ini memastikan bahwa aplikasi Anda hanya menerima permintaan yang valid dan Anda tidak pernah melewatkan pembaruan penting dari Microsoft Graph Webhooks.

Mengautentikasi dan Memverifikasi Token JWT

Setiap notifikasi dari Microsoft Graph menyertakan JSON Web Token (JWT) pada header Authorization. Anda wajib memverifikasi token ini sebelum memproses payload apa pun. Validasi JWT yang tepat melindungi sistem Anda dari permintaan yang tidak sah atau telah dimodifikasi.

Ikuti langkah-langkah berikut untuk mengautentikasi dan memverifikasi token JWT:

1. Periksa bahwa token belum kedaluwarsa. Token menyertakan waktu kedaluwarsa, dan Anda sebaiknya menolak token yang telah melewati waktu tersebut.

2. Pastikan bahwa token diterbitkan oleh Microsoft identity platform. Validasi tanda tangan token untuk memastikan token tidak diubah.

3. Pastikan klaim "audience" dalam token cocok dengan ID aplikasi Anda. Langkah ini memastikan token memang ditujukan untuk aplikasi Anda.

4. Verifikasi bahwa properti azp (authorized party) sesuai dengan nilai yang diharapkan untuk aplikasi Anda.

Tips: Selalu gunakan pustaka tepercaya untuk validasi JWT. Pustaka ini membantu Anda menghindari kesalahan umum dan menjaga keamanan aplikasi Anda.

Anda juga sebaiknya waspada terhadap kerentanan keamanan umum saat menangani token JWT:

• Kegagalan memverifikasi tanda tangan JWT dapat memungkinkan penyerang mengubah isi token tanpa terdeteksi.

• Menggunakan algoritma 'none' dalam pemrosesan JWT memungkinkan penyerang melewati pemeriksaan tanda tangan.

• Secret penandatanganan yang lemah memudahkan penyerang memalsukan token yang valid.

• Penyerang dapat menyisipkan parameter tertentu ke dalam header JOSE untuk memanipulasi cara sistem Anda memproses JWT.

Dengan mengikuti langkah-langkah dan kewaspadaan ini, Anda memastikan hanya notifikasi yang sah yang sampai ke aplikasi Anda.

Menangani Payload Notifikasi

Setelah Anda mengautentikasi notifikasi, Anda perlu memproses payload-nya secara aman. Payload notifikasi berisi informasi tentang peristiwa yang memicu webhook. Untuk menjaga integritas data dan mencegah masalah keamanan, Anda sebaiknya:

• Periksa bahwa semua field wajib tersedia dalam payload. Field yang hilang dapat menyebabkan kesalahan atau pemrosesan yang tidak lengkap.

• Sanitasi semua field teks sebelum menampilkannya atau menyimpannya di database Anda. Langkah ini mencegah serangan injeksi dan kerusakan data.

• Gunakan validasi skema untuk memastikan payload sesuai dengan struktur yang diharapkan. Validasi skema membantu Anda mendeteksi perubahan yang tidak terduga atau data yang tidak terbentuk dengan benar.

• Siapkan kode Anda untuk kemungkinan perubahan versi API. Parsing yang fleksibel memastikan aplikasi Anda tetap berfungsi meskipun Microsoft memperbarui format payload.

Catatan: Memvalidasi dan menyanitasi payload melindungi sistem Anda dari data yang tidak terbentuk dengan benar dan ancaman keamanan.

Menerapkan Logika Retry dan Backoff

Masalah jaringan atau gangguan sementara dapat menyebabkan pengiriman notifikasi gagal. Untuk menghindari kehilangan data, Anda memerlukan strategi retry dan backoff yang andal. Microsoft merekomendasikan penggunaan exponential backoff dan antrean terstruktur untuk mengelola retry.

Berikut adalah tabel yang merangkum mekanisme retry dan backoff yang umum:

Jika Anda tidak menerapkan logika percobaan ulang dan backoff yang tepat, aplikasi Anda berisiko kehilangan notifikasi atau menimbulkan inkonsistensi data. Permintaan yang gagal atau pembatasan laju (rate limiting) dapat membuat Anda tidak menerima pembaruan penting. Exponential backoff membantu Anda mengelola permintaan yang dibatasi dan mengurangi risiko sistem Anda, atau Microsoft Graph Webhooks, menjadi kewalahan.

🛡️ Praktik Terbaik: Selalu lacak jumlah percobaan ulang dan pindahkan pesan yang gagal ke antrean pembatalan setelah beberapa kali percobaan ulang. Pendekatan ini memungkinkan Anda menyelidiki dan menyelesaikan masalah yang terus berulang tanpa kehilangan data.

Dengan melakukan autentikasi token JWT, memvalidasi payload, dan menerapkan logika percobaan ulang yang andal, Anda membangun alur notifikasi yang aman dan tangguh. Langkah-langkah ini membantu Anda memproses setiap notifikasi dari Microsoft Graph Webhooks secara aman dan efisien.

Mengelola Langganan dan Pelacakan Perubahan

Mengotomatisasi Pembaruan Langganan

Anda perlu menjaga langganan webhook tetap aktif agar tidak kehilangan notifikasi. Langganan Microsoft Graph kedaluwarsa setelah jangka waktu tertentu. Jika Anda tidak memperbaruinya, aplikasi Anda berhenti menerima pembaruan. Anda dapat mengotomatisasi pembaruan dengan beberapa metode:

• Kirim permintaan HTTP PATCH untuk memperbarui tanggal kedaluwarsa setiap langganan.

• Jadwalkan permintaan PATCH ini untuk berjalan setiap hari. Hal ini menjaga langganan Anda tetap segar dan mencegah kedaluwarsa yang tidak terduga.

• Lacak stempel waktu kedaluwarsa untuk setiap langganan. Perbarui langganan apa pun yang hampir kedaluwarsa.

• Jika langganan kedaluwarsa, segera buat yang baru untuk memulihkan alur notifikasi.

Tips: Mengotomatisasi pembaruan mengurangi pekerjaan manual dan memastikan sistem Anda tetap terhubung ke Microsoft Graph.

Pemantauan dan Peringatan

Anda harus memantau kondisi alur webhook Anda. Atur peringatan untuk memberi tahu Anda jika langganan gagal diperbarui atau jika endpoint berhenti merespons. Gunakan logging untuk melacak notifikasi yang masuk dan upaya pembaruan. Hal ini membantu Anda mendeteksi masalah sebelum memengaruhi pengguna.

• Pantau status langganan dan tanggal kedaluwarsanya.

• Atur peringatan untuk pembaruan yang gagal atau notifikasi yang terlewat.

• Catat semua peristiwa dan kesalahan webhook untuk keperluan pemecahan masalah.

🛎️ Pemantauan proaktif membantu Anda memperbaiki masalah dengan cepat dan menjaga integrasi Anda tetap andal.

Menggunakan Delta Query untuk Pelacakan Perubahan

Delta query membantu Anda melacak perubahan pada resource SharePoint dan M365 secara efisien. Anda dapat menggunakannya untuk menerima hanya data baru atau yang diperbarui, sehingga mengurangi kebutuhan polling yang sering dan menurunkan risiko pembatasan (throttling).

• Delta query memungkinkan aplikasi Anda melacak perubahan tanpa mengunduh seluruh data setiap kali.

• Cara ini cocok untuk SharePoint dan M365, karena notifikasi hanya dikirim ketika ada perubahan.

• Anda menghemat bandwidth dan meningkatkan performa dengan menggunakan delta query.

Namun, delta query memiliki beberapa keterbatasan:

Catatan: Selalu uji implementasi delta query Anda untuk menangani keterbatasan ini dan memastikan pelacakan perubahan yang akurat.

Dengan mengotomatisasi pembaruan, memantau alur Anda, dan menggunakan delta query, Anda membangun sistem webhook yang andal dan efisien untuk SharePoint dan M365.

Anda dapat membangun webhook Microsoft Graph yang andal dengan mengikuti proses yang jelas. Mulailah dengan membuat langganan dan menggunakan delta query untuk melacak perubahan. Otomatisasi proses pembaruan langganan dan pantau pipeline Anda terhadap potensi masalah. Utamakan validasi, keamanan, dan ketahanan di setiap tahap. Untuk kesiapan produksi, tinjau checklist ini:

• Perbarui dokumentasi secara berkala dan pastikan tim pendukung selalu mendapat informasi.

• Jadwalkan pemeriksaan rutin untuk kondisi langganan.

• Gunakan pemindaian keamanan CI pipeline dan pertahankan jejak audit.

Terapkan praktik terbaik ini agar integrasi SharePoint dan M365 Anda tetap andal.

Pertanyaan Umum

Bagaimana cara memperbarui langganan webhook Microsoft Graph yang sudah kedaluwarsa?

Kirim permintaan PATCH ke endpoint Microsoft Graph /subscriptions/{id}. Perbarui field expirationDateTime. Jadwalkan proses ini agar berjalan setiap hari. Dengan cara ini, langganan Anda tetap aktif dan notifikasi tidak terlewat.

Apa yang harus dilakukan jika endpoint webhook Anda gagal validasi?

Pastikan endpoint Anda mengembalikan validationToken sebagai teks biasa di badan respons. Balas dengan status 200 OK. Pastikan endpoint Anda dapat diakses publik dan menggunakan HTTPS.

Bagaimana cara mengamankan endpoint webhook Anda?

Gunakan HTTPS untuk semua endpoint. Validasi token JWT pada setiap permintaan. Batasi akses dengan autentikasi dan daftar IP yang diizinkan. Pantau aktivitas yang tidak biasa. Audit pengaturan keamanan Anda secara berkala.

Mengapa Anda perlu menggunakan delta query dengan webhook?

Delta query membantu Anda melacak hanya data baru atau yang berubah. Cara ini mengurangi penggunaan bandwidth dan meningkatkan performa. Anda tidak perlu mengunduh seluruh data setiap kali, sehingga integrasi Anda menjadi lebih cepat dan efisien.

Apa cara terbaik untuk menangani notifikasi webhook yang gagal?

Terapkan logika retry dengan exponential backoff. Lacak percobaan ulang menggunakan header atau antrean. Pindahkan pesan yang gagal setelah beberapa kali percobaan ke antrean abandon. Selidiki kegagalan ini untuk mencegah kehilangan data.