Webhooks - Документация

Обзор

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

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

Webhooks для Workplace работают на той же платформе, что и Webhooks для Facebook.

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

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

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

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

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

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

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

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

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

С помощью параметра verify_token можно проверить, является ли сервер Facebook источником запроса HTTP GET, поступившего на ваш URL обратного вызова.

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

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

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

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

Темы Webhook

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

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

Страница

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

Поле подписки	Действие
`mention`	Активируется, когда страница с пользовательской интеграцией (бот) упоминается в группе.
`messages`	Активируется, когда странице с пользовательской интеграцией (боту) отправляется сообщение в рабочем чате.
`message_deliveries`	Активируется при доставке сообщения, отправленного страницей с пользовательской интеграцией (ботом).
`messaging_postbacks`	Активируется при нажатии кнопки обратной передачи в рабочем чате.
`message_reads`	Активируется, когда получатель прочитывает сообщение, отправленное страницей с пользовательской интеграцией (ботом).

Группа

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

Поле подписки	Поведение
`posts`	Активируется при добавлении, обновлении или удалении публикации в группе.
`comments`	Активируется при добавлении, обновлении или удалении комментария к публикации в группе.
`membership`	Активируется при изменении членства в группе.

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

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

Поле подписки	Поведение
`status`	Активируется, когда пользователь публикует или редактирует обновление статуса в своем профиле.
`events`	Активируется при создании, принятии или отклонении события пользователем.
`message_sends`	Активируется, когда пользователь отправляет сообщение в Чате Workplace.

Ссылка

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

Поле подписки	Поведение
`preview`	Активируется, когда Workplace необходимо получить информацию об URL.
`collection`	Актуально только для приложений в списке разрешенных, которые поддерживают иерархическую навигацию редактора публикаций.

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

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

`sessions`

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

Событие Поведение

Событие	Поведение
`log_in`	Пользователь вошел в аккаунт Workplace на сайте или в мобильном приложении, используя пароль или функцию единого входа.
`log_out`	Пользователь вышел из аккаунта Workplace на сайте или в мобильном приложении, используя пароль или функцию единого входа. Не активируется при принудительном выходе, инициированном администратором (см. событие `admin_force_log_out`).

log_in

Пользователь вошел в аккаунт Workplace на сайте или в мобильном приложении, используя пароль или функцию единого входа.

log_out

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

Не активируется при принудительном выходе, инициированном администратором (см. событие admin_force_log_out).

`passwords`

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

Событие	Действие
`password_change`	Пароль пользователя был изменен в настройках аккаунта или в результате восстановления.
`password_reset_request`	Запущено восстановление пароля пользователя. На его электронный адрес отправлен код.
`password_reset_wrong_code`	Пользователь ввел неправильный код восстановления для сброса пароля.
`password_reset_success`	Пароль восстановлен.

`admin_activity`

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

Событие	Поведение
`admin_set_to_unclaimed`	Администратор отметил аккаунт пользователя как незанятый на панели администратора или через Account Management API.
`admin_force_log_out`	Администратор выполнил принудительный выход из аккаунта пользователя на всех устройствах через панель администратора.
`admin_deactivate`	Администратор деактивировал аккаунт на панели администратора или с помощью Account Management API.
`admin_activate_account`	Администратор активировал аккаунт на панели администратора или с помощью Account Management API.
`force_password_reset`	Администратор принудительно сбросил пароль пользователя на панели администратора.
`admin_create_account`	Администратор создал аккаунт на панели администратора.

`two_factor`

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

Событие	Поведение
`two_factor_enable`	Пользователь включил двухфакторную аутентификацию на вкладке "Настройки". При этом факт подтверждения номера телефона не имеет значения.
`two_factor_disable`	Пользователь отключил двухфакторную аутентификацию на вкладке "Настройки". При этом факт отключения этой функции для определенного телефона не имеет значения.