Як створити надійні вебхуки Microsoft Graph для SharePoint і M365

By Mirko Peters · 2025-11-16

Створіть надійні вебхуки Microsoft Graph для SharePoint і M365 з безпечною валідацією, автоматичним продовженням підписок і стабільною доставкою сповіщень.

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

Створювати надійні вебхуки Microsoft Graph для SharePoint і M365 може бути складно навіть досвідченим розробникам. Ви можете побачити помилки валідації, якщо ваш endpoint не повертає токен валідації або не відповідає статусом 200 OK. Серед типових проблем: endpoint заблокований брандмауерами, помилки мережевої конфігурації або втручання проміжного ПЗ (middleware). Пропущені повторні спроби та прострочені підписки часто виникають, коли сервіс не отримує запит на валідацію або endpoint недоступний із публічної мережі. Ви дізнаєтесь, як уникнути цих пасток і побудувати надійний та безпечний конвеєр сповіщень, а також отримаєте практичний чек-лист і найкращі практики.

Головне

• Вебхуки Microsoft Graph надають сповіщення про зміни в Microsoft 365 у реальному часі, тож не потрібно постійно опитувати сервіс.

• Переконайтеся, що ваш endpoint для вебхука доступний із публічної мережі та використовує HTTPS, щоб забезпечити безпеку й надійність.

• Швидко відповідайте на запити валідації, повертаючи токен валідації, щоб успішно активувати підписку на вебхук.

• Впровадьте надійну стратегію повторних спроб і backoff, щоб обробляти збої доставки сповіщень і запобігати втраті даних.

• Автоматизуйте продовження підписок і моніторте конвеєр вебхуків, щоб забезпечити безперервну та надійну доставку сповіщень.

Основи вебхуків Microsoft Graph

Що таке вебхуки Microsoft Graph

Вебхук — це HTTP-запит, який ініціюється подією в системі-джерелі та надсилається до цільової системи, часто з корисним навантаженням даних. Вебхуки працюють автоматично: їх надсилають одразу, щойно в системі-джерелі відбувається відповідна подія.

Вебхуки Microsoft Graph дозволяють отримувати сповіщення про зміни у вашому середовищі Microsoft 365 у реальному часі. Це означає, що не потрібно постійно опитувати Microsoft Graph на наявність оновлень. Натомість ваш застосунок отримує сповіщення щойно відбувається щось важливе. Так ви залишаєтеся в курсі змін і синхронізовані з даними, доступними через Microsoft Graph. Крім того, зникає потреба в інфраструктурі опитування, коли ви часто надсилаєте запити до Microsoft Graph, щоб перевіряти останні зміни.

Можна налаштувати сповіщення для багатьох типів подій, зокрема:

• Повідомлення

• Події

• Контакти

• Користувачі

• Групи

• Розмови

• Файли OneDrive

• Сповіщення

Наприклад, ви можете автоматично створювати обліковий запис у сторонній системі обліку часу, коли новий користувач приєднується до вашої організації. Також можна запускати обробку вмісту, наприклад обробку звітів про витрати, щойно хтось додає новий файл до бібліотеки документів SharePoint або папки OneDrive.

Чому важлива надійність

Вебхуки Microsoft Graph відіграють ключову роль у тому, щоб інтеграції з SharePoint і Microsoft 365 залишалися чутливими та актуальними. Коли конвеєр вебхуків працює надійно, ваші застосунки реагують на зміни в реальному часі. Користувачі завжди бачать найактуальніші дані, що покращує їхній досвід і знижує ризик застарілої інформації.

Проте проблеми з надійністю можуть спричинити серйозні наслідки:

• Збої вебхуків можуть порушити роботу застосунку, якщо на них не реагувати належним чином.

• Раптові сплески трафіку можуть перевантажити сервери, що призводить до простоїв і втрати запитів вебхуків.

• Невміння обробити вебхуки може призвести до втрати даних і неузгодженості, якщо немає механізму повторної передачі.

• Незахищені URL вебхуків можна експлуатувати, що дозволяє зловмисникам надсилати пошкоджені дані.

Щоб побудувати надійне рішення, варто поєднувати вебхуки з delta-запитами, щоб ефективно відстежувати зміни. Також потрібно налаштувати процеси регулярної перевірки та продовження підписок. Для ресурсів, які часто оновлюються, пакетування запитів допомагає керувати навантаженням.

Налаштування та валідація вебхуків

Налаштування вебхуків Microsoft Graph для SharePoint і M365 передбачає кілька важливих кроків. Потрібно зареєструвати вебхук, обробляти запити на перевірку та захистити кінцеву точку. Кожен крок відіграє критичну роль у тому, щоб конвеєр сповіщень працював надійно і безпечно.

Реєстрація вебхуків Microsoft Graph

Почніть зі створення передплати на вебхук. Цей процес дозволяє вашому застосунку отримувати сповіщення про зміни в ресурсах Microsoft 365. Щоб зареєструвати вебхук, виконайте такі кроки:

1. Створіть загальнодоступну кінцеву точку, яка використовує HTTPS. Ця кінцева точка отримуватиме сповіщення від Microsoft Graph.

2. Надішліть запит POST до кінцевої точки /subscriptions у Microsoft Graph.

3. У запиті на передплату вкажіть:

   • changeType: типи змін, які потрібно відстежувати, наприклад «created», «updated» або «deleted».

   • notificationUrl: URL вашої кінцевої точки вебхука.

   • resource: ресурс, за яким потрібно стежити, наприклад «/users» або «/drive/root».

   • expirationDateTime: дата й час, коли передплата має закінчитися.

   • Необов’язкові властивості, наприклад clientState, допомагають перевірити джерело сповіщень.

Приклад запиту на передплату:

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"
}

Кінцева точка має бути загальнодоступною та захищеною HTTPS. Microsoft Graph перевіряє URL сповіщень, перш ніж завершити передплату. Передплати потрібно регулярно поновлювати, щоб продовжувати отримувати сповіщення. Кінцева точка має своєчасно і стабільно повертати HTTP-відповіді, щоб не пропускати сповіщення.

Ось короткий огляд обов’язкових полів для реєстрації:

Обробка запитів на перевірку

Після реєстрації вебхука Microsoft Graph надсилає запит на перевірку до вашої кінцевої точки. Щоб завершити процес передплати, потрібно правильно відповісти. Коли кінцева точка отримує запит GET із параметром рядка запиту validationToken, слід повернути цей токен у тілі відповіді як простий текст зі статусом 200 OK.

• Якщо не повернути validationToken, виникне помилка перевірки. Це означає, що Microsoft Graph не може підтвердити вашу кінцеву точку, і ви не отримуватимете сповіщення.

• Щоб перевірити, що запити надходять із вашої передплати, варто використовувати властивість clientState.

• Завжди повертайте validationToken у тілі відповіді як простий текст протягом 10 секунд.

💡 Порада: швидка й точна відповідь на запити перевірки гарантує, що передплата на вебхук активується без проблем.

Безпека HTTPS і кінцевої точки

Захист кінцевої точки вебхука є обов’язковим. Вебхуки Microsoft Graph вимагають шифрування HTTPS, щоб захищати чутливі дані під час передавання. Перевіряйте вхідні запити, звіряючи підпис, створений із використанням спільного секретного ключа. Для URL зворотного виклику використовуйте складні, випадково згенеровані шляхи, щоб їх важче було вгадати.

• Додайте до API-кінцевих точок Microsoft Graph IP-адреси у списку дозволених.

• Передавайте токени автентифікації в заголовках запитів.

• Відстежуйте використання API, щоб виявляти незвичні шаблони або сплески активності.

• Обмежте доступ до Microsoft Graph і Outlook API. Доступ мають лише уповноважені працівники, і слід увімкнути багатофакторну автентифікацію.

• Впроваджуйте сучасні рішення для захисту кінцевих точок, які використовують поведінкову аналітику та машинне навчання для виявлення загроз.

• Регулярно проводьте аудит безпеки, щоб знаходити вразливості та усувати їх.

Кожен зворотний виклик webhook містить підписаний JSON Web Token (JWT) у заголовку Authentication вхідного HTTPS-запиту. Для перевірки цілісності токена можна використовувати стандартні техніки валідації JWT за OpenID Connect.

Для всіх кінцевих точок webhook обов’язково використовуйте HTTPS. Ця вимога захищає ваші дані та забезпечує відповідність стандартам безпеки Microsoft. Захист кінцевої точки допомагає запобігти несанкціонованому доступу та атакам.

Виконавши ці кроки, ви налаштуєте надійний і безпечний конвеєр Microsoft Graph Webhooks для SharePoint та M365. Ваш застосунок отримуватиме сповіщення своєчасно й безпечно.

Обробка та захист сповіщень

Після налаштування кінцевої точки webhook потрібно безпечно та надійно обробляти вхідні сповіщення. Цей крок гарантує, що ваш застосунок приймає лише дійсні запити і не пропускає важливих оновлень від Microsoft Graph Webhooks.

Автентифікація та перевірка токенів JWT

Кожне сповіщення від Microsoft Graph містить JSON Web Token (JWT) у заголовку Authorization. Перш ніж обробляти будь-яке навантаження, ви маєте перевірити цей токен. Належна перевірка JWT захищає вашу систему від неавторизованих або підроблених запитів.

Виконайте такі кроки для автентифікації та перевірки токенів JWT:

1. Перевірте, чи не минув термін дії токена. Токени містять час закінчення дії, і будь-який токен із простроченим терміном слід відхиляти.

2. Переконайтеся, що токен видала платформа ідентифікації Microsoft. Перевірте підпис токена, щоб упевнитися, що його не змінили.

3. Переконайтеся, що твердження «audience» у токені збігається з ідентифікатором вашого застосунку. Цей крок підтверджує, що токен призначено саме для вашого застосунку.

4. Перевірте, чи властивість azp (authorized party) збігається з очікуваним значенням для вашого застосунку.

Порада: Завжди використовуйте перевірені бібліотеки для валідації JWT. Вони допомагають уникнути типових помилок і зберегти безпеку застосунку.

Під час роботи з токенами JWT також варто остерігатися поширених вразливостей безпеки:

• Якщо не перевіряти підпис JWT, зловмисники можуть змінити вміст токена непоміченими.

• Використання алгоритму 'none' під час обробки JWT дає зловмисникам змогу обійти перевірку підпису.

• Слабкі секрети підпису спрощують зловмисникам підробку дійсних токенів.

• Зловмисники можуть впроваджувати певні параметри в заголовок JOSE, щоб змінити спосіб обробки JWT вашою системою.

Дотримуючись цих кроків і запобіжних заходів, ви гарантуєте, що до вашого застосунку потрапляють лише легітимні сповіщення.

Обробка навантажень сповіщень

Після автентифікації сповіщення потрібно безпечно обробити його навантаження. Навантаження сповіщень містять інформацію про подію, яка спричинила спрацьовування webhook. Щоб зберегти цілісність даних і запобігти проблемам безпеки, слід:

• Перевірити наявність усіх обов’язкових полів у навантаженні. Відсутні поля можуть спричинити помилки або неповну обробку.

• Очищайте всі текстові поля перед відображенням або збереженням у базі даних. Цей крок запобігає ін’єкційним атакам і пошкодженню даних.

• Використовуйте валідацію за схемою, щоб переконатися, що навантаження відповідає очікуваній структурі. Валідація за схемою допомагає виявити несподівані зміни або некоректні дані.

• Підготуйте код до можливих змін версій API. Гнучкий розбір даних гарантує, що застосунок продовжить працювати, навіть якщо Microsoft змінить формат навантаження.

Примітка: Валідація та очищення навантажень захищають вашу систему від некоректних даних і загроз безпеці.

Реалізація логіки повторних спроб і backoff

Мережеві збої або тимчасові простої можуть призвести до невдалої доставки сповіщень. Щоб уникнути втрати даних, потрібна надійна стратегія повторних спроб і backoff. Microsoft рекомендує використовувати експоненційний backoff і структуровані черги для керування повторними спробами.

Ось таблиця з узагальненням поширених механізмів повторних спроб і backoff:

Якщо ви не реалізуєте належну логіку повторних спроб і експоненційної затримки, ваш застосунок ризикує втратити сповіщення або створити невідповідності в даних. Невдалі запити або обмеження частоти можуть завадити отриманню критично важливих оновлень. Експоненційна затримка допомагає керувати запитами, що obмежені за частотою, і зменшує ймовірність перевантаження вашої системи або Microsoft Graph Webhooks.

🛡️ Найкраща практика: Завжди відстежуйте спроби повтору та переносіть повідомлення, які не вдалося обробити, до черги відмов після кількох повторів. Такий підхід дає змогу досліджувати й усувати стійкі проблеми без втрати даних.

Завдяки автентифікації JWT-токенів, перевірці корисного навантаження та надійній логіці повторних спроб ви створюєте безпечний і стійкий конвеєр сповіщень. Ці кроки допомагають безпечно й ефективно обробляти кожне сповіщення від Microsoft Graph Webhooks.

Керування підписками та відстеження змін

Автоматизація поновлення підписок

Щоб не пропускати сповіщення, потрібно підтримувати активність підписок вебхука. Підписки Microsoft Graph спливають через визначений період. Якщо їх не поновлювати, ваш застосунок перестане отримувати оновлення. Поновлення можна автоматизувати кількома способами:

• Надсилайте HTTP PATCH-запити, щоб оновити дату закінчення дії кожної підписки.

• Плануйте ці PATCH-запити на щоденний запуск. Так підписки залишаються актуальними, і їх не буде несподівано закрито через завершення терміну дії.

• Відстежуйте позначку часу закінчення дії для кожної підписки. Поновлюйте будь-яку підписку, термін дії якої близький до завершення.

• Якщо термін дії підписки минув, одразу створіть нову, щоб відновити потік сповіщень.

Порада: Автоматизація поновлень зменшує ручну роботу та гарантує, що ваша система залишається підключеною до Microsoft Graph.

Моніторинг і сповіщення

Ви маєте стежити за станом конвеєра вебхуків. Налаштуйте сповіщення, які повідомлять вас, якщо підписка не поновилася або ваша кінцева точка перестала відповідати. Використовуйте журналювання, щоб відстежувати вхідні сповіщення та спроби поновлення. Це допоможе помітити проблеми до того, як вони вплинуть на користувачів.

• Стежте за статусом підписок і датами закінчення їх дії.

• Налаштуйте сповіщення про невдалі поновлення або пропущені сповіщення.

• Журналюйте всі події вебхуків і помилки для усунення несправностей.

🛎️ Проактивний моніторинг допомагає швидко усувати проблеми та підтримувати надійність інтеграції.

Використання delta-запитів для відстеження змін

Delta-запити допомагають ефективно відстежувати зміни у ресурсах SharePoint і M365. Їх можна використовувати, щоб отримувати лише нові або оновлені дані, що зменшує потребу в частому опитуванні та знижує ризик обмеження частоти запитів.

• Delta-запити дозволяють вашому застосунку відстежувати зміни без завантаження всіх даних щоразу.

• Вони добре працюють із SharePoint і M365, надсилаючи сповіщення лише тоді, коли щось змінюється.

• Використовуючи delta-запити, ви заощаджуєте пропускну здатність і покращуєте продуктивність.

Водночас у delta-запитів є деякі обмеження:

Примітка: Завжди тестуйте реалізацію delta-запитів, щоб врахувати ці обмеження та забезпечити точне відстеження змін.

Автоматизувавши поновлення, моніторинг конвеєра та використання delta-запитів, ви побудуєте надійну й ефективну систему вебхуків для SharePoint і M365.

Ви можете побудувати надійні вебхуки Microsoft Graph, дотримуючись чіткого процесу. Почніть із створення підписок і використання delta-запитів для відстеження змін. Автоматизуйте поновлення та стежте за роботою конвеєра, щоб вчасно помічати проблеми. Пріоритетом на кожному етапі мають бути перевірка, безпека та стійкість. Щоб переконатися, що рішення готове до продуктивного середовища, перегляньте цей контрольний список:

• Регулярно оновлюйте документацію та інформуйте команди підтримки.

• Плануйте регулярні перевірки стану підписок.

• Використовуйте сканування безпеки в CI-конвеєрі та ведіть журнали аудиту.

Застосовуйте ці найкращі практики, щоб інтеграції з SharePoint і Microsoft 365 залишалися надійними.

Поширені запитання

Як поновити прострочену підписку на вебхук Microsoft Graph?

Надішліть запит PATCH до кінцевої точки Microsoft Graph /subscriptions/{id}. Оновіть поле expirationDateTime. Налаштуйте щоденний запуск цього процесу. Так підписки залишатимуться активними, і ви не пропускатимете сповіщення.

Що робити, якщо кінцева точка вебхука не проходить перевірку?

Переконайтеся, що кінцева точка повертає validationToken як звичайний текст у тілі відповіді. Відповідайте зі статусом 200 OK. Переконайтеся, що кінцева точка доступна публічно та використовує HTTPS.

Як захистити кінцеву точку вебхука?

Використовуйте HTTPS для всіх кінцевих точок. Перевіряйте токени JWT у кожному запиті. Обмежуйте доступ за допомогою автентифікації та білих списків IP-адрес. Стежте за незвичайною активністю. Регулярно перевіряйте налаштування безпеки.

Навіщо використовувати delta-запити з вебхуками?

Delta-запити дозволяють відстежувати лише нові або змінені дані. Це зменшує навантаження на канал передачі даних і підвищує продуктивність. Ви не завантажуєте всі дані щоразу, тож інтеграція працює швидше й ефективніше.

Який найкращий спосіб обробляти невдалі сповіщення вебхука?

Реалізуйте логіку повторних спроб з експоненційною затримкою. Відстежуйте спроби за допомогою заголовків або черг. Переміщуйте повідомлення, які не вдалися після кількох повторів, у чергу відмов. Досліджуйте ці збої, щоб запобігти втраті даних.