Webhooks

Обзор

С помощью Webhooks приложения с пользовательскими интеграциями могут подписываться на события в Workplace и получать обновления в режиме реального времени. Когда что-то изменяется в Workplace, на URL обратного вызова каждого приложения, подписанного на соответствующую тему Webhook, отправляется запрос HTTPS POST.

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

Webhooks для Workplace работают на основе того же фреймворка, что и Webhooks для API Graph.

Подписка на темы Webhook

В диалоге редактирования пользовательской интеграции есть вкладки для каждой темы Webhook, доступной приложениям в Workplace.

Раздел настройки Webhooks в диалоге редактирования пользовательской интеграции

Чтобы подписаться на тему Webhook, укажите URL обратного вызова и маркер подтверждения, а затем выберите нужные поля подписки.

Обработка запросов подтверждения

При добавлении новой или изменении существующей подписки серверы Meta проверяют действительность сервера обратного вызова, отправляя на его URL запрос GET.

К URL добавляется строка запроса со следующими параметрами:

• hub.mode — в этом параметре передается строка "subscribe";
• hub.challenge — случайная строка;
• hub.verify_token — значение verify_token, указанное при создании подписки.

Когда ваша конечная точка получает запрос подтверждения, она должна:

• Подтвердить, что значение hub.verify_token соответствует строке, указанной вами в поле "Маркер проверки" при настройке Webhook.
• Передать в ответ значение hub.challenge.

Безопасность Webhook

Все вызовы Webhook на заданные разработчиком URL обратного вызова выполняются по протоколу HTTPS. Таким образом обеспечивается безопасность полезных данных на транспортном уровне.

Для более надежной защиты в каждый запрос POST добавляется используемый для HTTP заголовок X-Hub-Signature-256, который подтверждает, что данные поступили с сервера Meta.

Подробную информацию см. в документации по фреймворку Webhooks.

Все вызовы Webhook на заданные разработчиком URL обратного вызова выполняются по протоколу HTTPS. Таким образом обеспечивается безопасность полезных данных на транспортном уровне.

Подписка на Webhooks через вызов API

В вызовах API для чтения или изменения подписок Webhook необходимо использовать маркер приложения, а не пользовательской интеграции. Маркер приложения образуется путем объединения ID приложения, символа "|" и секрета приложения.

Пример:

Получение текущих подписок Webhook (с указанием маркера приложения)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

Добавление подписки Webhook (с указанием маркера приложения)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

Устранение неполадок с подписками приложения на страницы

Если вы не получаете уведомления Webhook, когда должны, рекомендуем проверить, правильно ли настроена подписка между страницей и приложением. Она должна настраиваться автоматически, однако иногда возникают проблемы. Например, если уведомления Webhook долго не доставляются, подписка может быть удалена. Для стороннего приложения в этом случае появится оповещение на панели приложений.

Для проверки подписки можно выполнить следующий вызов API.

Получение текущей подписки приложения на страницу (с указанием маркера приложения)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

Чтобы создать подписку заново, можно использовать следующий вызов API.

Повторное создание текущей подписки приложения на страницу (с указанием маркера приложения)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Темы Webhook

Действия в Workplace группируются в темы. У каждой темы есть ряд полей, которые связаны с соответствующими событиями. Приложения могут подписываться на обновления Webhook по темам и на определенные поля каждой темы.

Сейчас в Workplace предлагаются перечисленные ниже темы и группы Webhook.

Страница

Дополнительную информацию см. в справке по этой теме.

Группы

Дополнительную информацию см. в справке по этой теме.

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

Дополнительную информацию см. в справке по этой теме.

Безопасность

Дополнительную информацию см. в справке по этой теме.

admin_activity

Эти события активируются при добавлении или удалении администратора в сообществе Workplace.

compromised_credentials

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

files

Эти события активируются при выполнении действий с файлами в Workplace.

groups

Эти события активируются, когда пользователь создает группу для сотрудничества в Workplace или вступает в нее.

integrations

Эти события активируются, когда администратор создает интеграцию или изменяет ее свойства.

invites

Эти события активируются, когда пользователь присоединяется к сообществу Workplace, отправляя себе приглашение.

passwords

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

sessions

Эти события активируются, когда пользователь входит в аккаунт Workplace или выходит из него.

two_factor

Эти события активируются, когда пользователь включает или отключает двухфакторную аутентификацию.

reseller_events

События, связанные с торговым посредником.

Ссылки

Дополнительную информацию см. в справке по этой теме.

Библиотека знаний

Дополнительная информация доступна в Документации для API Graph категории Библиотеки знаний.