Как создать надёжные вебхуки 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 может стать непростой задачей даже для опытных разработчиков. Вы можете столкнуться с ошибками проверки, если ваша конечная точка не возвращает токен проверки или не отвечает статусом 200 OK. Типичные проблемы включают конечные точки, заблокированные брандмауэрами, ошибки в настройке сети или вмешательство промежуточного ПО. Пропущенные повторные попытки и истёкшие подписки часто возникают, когда служба не получает запрос на проверку или когда конечные точки недоступны из публичной сети. В этой статье вы узнаете, как избежать этих ловушек и создать надёжный и безопасный конвейер уведомлений, а также получите практический чек-лист и рекомендации по лучшим практикам.

Главное

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

• Убедитесь, что ваша конечная точка вебхука доступна из публичной сети и использует HTTPS для обеспечения безопасности и надёжности.

• Быстро отвечайте на запросы проверки, возвращая токен проверки, чтобы успешно активировать подписку на вебхук.

• Внедрите надёжную стратегию повторных попыток и отсрочки, чтобы обрабатывать сбои доставки уведомлений и предотвращать потерю данных.

• Автоматизируйте продление подписок и отслеживайте конвейер вебхуков, чтобы обеспечить непрерывную и надёжную доставку уведомлений.

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

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

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

Вебхуки Microsoft Graph позволяют получать уведомления об изменениях в вашей среде Microsoft 365 в режиме реального времени. Это означает, что не нужно постоянно опрашивать Microsoft Graph на наличие обновлений. Вместо этого ваше приложение получает уведомление сразу, как только происходит что-то важное. Это позволяет оставаться в курсе событий и синхронизировать данные, доступные через Microsoft Graph. Кроме того, отпадает необходимость в инфраструктуре опроса, при которой вы часто отправляете запросы в Microsoft Graph, чтобы проверить наличие последних изменений.

Вы можете настроить уведомления для многих типов событий, например:

• Сообщения

• События

• Контакты

• Пользователи

• Группы

• Беседы

• Файлы OneDrive

• Оповещения

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

Почему важна надёжность

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

Однако проблемы с надёжностью могут привести к серьёзным последствиям:

• Сбои вебхуков могут нарушить работу приложения, если на них не реагировать должным образом.

• Внезапные всплески трафика могут перегрузить серверы, что приведёт к простоям и потере запросов вебхуков.

• Отсутствие обработки вебхуков может привести к потере данных и несогласованности, если не предусмотрен механизм повторной передачи.

• Незащищённые URL вебхуков могут быть использованы злоумышленниками для отправки искажённых данных.

Чтобы построить надёжное решение, стоит сочетать вебхуки с дельта-запросами для эффективного отслеживания изменений. Также нужно настроить процессы регулярной проверки и продления подписок. Для ресурсов, которые часто обновляются, пакетная обработка запросов помогает управлять нагрузкой.

Настройка и проверка вебхуков

Настройка webhook-уведомлений Microsoft Graph для SharePoint и Microsoft 365 включает несколько важных шагов. Нужно зарегистрировать webhook, обработать запросы валидации и защитить конечную точку. Каждый шаг играет критическую роль в том, чтобы конвейер уведомлений работал надёжно и безопасно.

Регистрация webhook-уведомлений Microsoft Graph

Начните с создания подписки webhook. Этот процесс позволяет вашему приложению получать уведомления об изменениях в ресурсах Microsoft 365. Чтобы зарегистрировать webhook, выполните следующие шаги:

1. Создайте общедоступную конечную точку, которая использует HTTPS. Эта конечная точка будет получать уведомления от Microsoft Graph.

2. Отправьте POST-запрос на конечную точку /subscriptions в Microsoft Graph.

3. В запросе на подписку укажите:

   • changeType: типы изменений, которые нужно отслеживать, например «created», «updated» или «deleted».

   • notificationUrl: URL вашей конечной точки webhook.

   • 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-ответы, иначе уведомления могут быть пропущены.

Ниже приведена сводка обязательных полей для регистрации:

Обработка запросов валидации

После регистрации webhook Microsoft Graph отправляет запрос валидации на вашу конечную точку. Чтобы завершить процесс подписки, необходимо корректно ответить. Когда конечная точка получает GET-запрос с параметром запроса validationToken, нужно вернуть этот токен в теле ответа как обычный текст и вернуть статус 200 OK.

• Если не вернуть validationToken, возникнет ошибка валидации. Это означает, что Microsoft Graph не может подтвердить вашу конечную точку, и уведомления не будут поступать.

• Используйте свойство clientState, чтобы проверить, что запросы поступают из вашей подписки.

• Всегда возвращайте validationToken в теле ответа как обычный текст в течение 10 секунд.

💡 Совет: быстрый и точный ответ на запросы валидации гарантирует, что подписка webhook активируется без проблем.

HTTPS и безопасность конечной точки

Защита конечной точки webhook необходима. Webhook-уведомления Microsoft Graph требуют шифрования HTTPS, чтобы защитить конфиденциальные данные при передаче. Проверяйте входящие запросы, сверяя подпись, созданную с помощью общего секретного ключа. Используйте сложные, случайно сгенерированные пути для URL обратного вызова, чтобы их было труднее угадать.

• Добавьте IP-фильтрацию (список разрешённых IP-адресов) для конечных точек Microsoft Graph API.

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

• Отслеживайте использование API, чтобы выявлять необычные шаблоны или всплески активности.

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

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

• Регулярно проводите аудит безопасности, чтобы находить уязвимости и устранять их.

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

Для всех конечных точек webhook必须 использовать HTTPS. Это требование защищает ваши данные и обеспечивает соответствие стандартам безопасности Microsoft. Защита конечной точки помогает предотвратить несанкционированный доступ и атаки.

Выполнив эти шаги, вы настроите надежный и безопасный конвейер Microsoft Graph Webhooks для SharePoint и Microsoft 365. Ваше приложение будет получать уведомления своевременно и безопасно.

Обработка и защита уведомлений

После настройки конечной точки 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 изменит формат данных.

Примечание: Проверка и очистка данных уведомлений защищает вашу систему от искаженных данных и угроз безопасности.

Реализация логики повторных попыток и отсрочки

Сбои сети или временные отключения могут привести к неудачной доставке уведомлений. Чтобы избежать потери данных, нужна надежная стратегия повторных попыток и отсрочки. Microsoft рекомендует использовать экспоненциальную отсрочку и структурированные очереди для управления повторными попытками.

Ниже приведена таблица с описанием распространенных механизмов повторных попыток и отсрочки:

Если не реализовать правильную логику повторов и экспоненциальной задержки, ваше приложение рискует потерять уведомления или получить несогласованность данных. Неудачные запросы или ограничение частоты запросов могут помешать получению важных обновлений. Экспоненциальная задержка помогает управлять запросами, на которые наложено ограничение, и снижает риск перегрузки вашей системы или 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 и M365 оставались надёжными.

Часто задаваемые вопросы

Как продлить истёкшую подписку вебхука Microsoft Graph?

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

Что делать, если конечная точка вебхука не проходит проверку?

Убедитесь, что конечная точка возвращает validationToken как открытый текст в теле ответа. Отвечайте со статусом 200 OK. Проверьте, что конечная точка доступна публично и использует HTTPS.

Как защитить конечную точку вебхука?

Используйте HTTPS для всех конечных точек. Проверяйте токены JWT в каждом запросе. Ограничивайте доступ с помощью аутентификации и белого списка IP-адресов. Отслеживайте необычную активность. Регулярно проверяйте настройки безопасности.

Зачем использовать delta-запросы с вебхуками?

Delta-запросы позволяют отслеживать только новые или изменённые данные. Это снижает нагрузку на канал передачи и повышает производительность. Вам не нужно каждый раз загружать все данные, поэтому интеграция работает быстрее и эффективнее.

Как лучше всего обрабатывать неудачные уведомления вебхука?

Реализуйте логику повторных попыток с экспоненциальной задержкой. Отслеживайте количество попыток с помощью заголовков или очередей. Перемещайте сообщения, которые не обработаны после нескольких повторов, в очередь отброшенных сообщений. Расследуйте такие сбои, чтобы предотвратить потерю данных.