Вебхуки

Введение

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

Используйте вебхуки, чтобы выполнять пользовательские действия на стороне любого приложения или веб-сайта, которым вы пользуетесь, на основе различных событий в ONLYOFFICE Apps.

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

Создание нового вебхука

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

После создания и настройки конечной точки вы можете создавать вебхуки в рабочем пространстве. Чтобы создать новый вебхук,

1. Откройте раздел Инструменты разработчика, нажав ссылку Инструменты разработчика, доступную на левой панели в любом разделе (Файлы, Комнаты, Формы).

   Обратите внимание

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

   Администраторы могут как использовать ссылку Инструменты разработчика слева, так и перейти в этот раздел из Настроек рабочего пространства, нажав меню в левом нижнем углу и выбрав пункт Настройки -> Инструменты разработчика.

2. В разделе Инструменты разработчика перейдите в раздел Вебхуки.

3. Нажмите кнопку Создать вебхук.

4. Задайте необходимые параметры:

   

   • Имя вебхука — имя-идентификатор для удобной работы с вебхуком в рабочем пространстве.

   • URL-адрес полезной нагрузки — адрес конечной точки, на которую должен быть отправлен вебхук.

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

     

   • Проверка SSL-сертификатов — по умолчанию этот параметр включен, чтобы проверять SSL-сертификаты при доставке полезной нагрузки. Отключать этот параметр не рекомендуется.

   • Событие для запуска этого вебхука — используйте вариант Отправить все или установите переключатель Отдельные события и выберите только определенные триггеры, то есть события при изменении объектов рабочего пространства, таких как пользователи, группы, файлы, папки, комнаты, формы и ИИ-агенты. Например, пользователь создан, приглашен, обновлен, удален и т. д.

   • Целевой идентификатор — идентификатор пользователя, группы, файла или папки, позволяющий отслеживать изменения одного объекта.

   

5. URL-адрес полезной нагрузки должен отвечать статусом 200 на http-запрос с методом HEAD.

6. Нажмите кнопку Создать.

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

Управление вебхуками

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

• Настройки — изменить настройки вебхука, заданные при его создании.
• История вебхука — просмотреть историю доставки вебхука.
• Удалить вебхук — удалить вебхук.

Нажмите на вебхук, чтобы просмотреть историю вебхука

При просмотре истории вы можете фильтровать вебхуки по дате доставки или статусу (Не отправлено, 2XX, 3XX, 4XX, 5XX). Нажмите кнопку фильтра , выберите нужные параметры и нажмите Применить.

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

Нажмите значок рядом с нужным вебхуком и выберите пункт Сведения о вебхуке в контекстном меню.

Доступны следующие сведения:

• Статус — статус ответа.
• Идентификатор события — идентификатор события.
• Тип события — событие, вызвавшее срабатывание вебхука.
• Время события — дата, когда произошло событие.
• Время доставки — дата, когда был получен ответ от конечной точки.

В разделах Запрос/Ответ также можно просмотреть заголовок POST-запроса, тело POST-запроса, заголовок POST-ответа и тело POST-ответа. Используйте значок , чтобы скопировать заголовок или тело запроса или ответа в буфер обмена.

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

Технические подробности

Для работы используются следующие два сервиса:

1. ASC.Web.Studio предоставляет методы отправки вебхуков и запускает WorkerService.

   WorkerService — подписывается на получение сообщений от брокера (по умолчанию используется, например, RabbitMQ), который хранит информацию о новых вебхуках, ожидающих отправки. Сообщения, полученные от брокера, помещаются в очередь, после чего очередь постоянно опрашивается и асинхронно обращается к ASC.Webhoks.Service для отправки вебхуков.

2. ASC.Webhooks.Core предоставляет методы публикации вебхуков в базе данных и брокере сообщений, а также методы работы с базой данных.

Подробнее об API ONLYOFFICE Apps см. на сайте api.onlyoffice.com.