Вебхуки

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

Вебхуки настраиваются на уровне пространства.

Механизмом выполнения вебхука является HTTP-запрос по методу POST.

??? note “Пример” В Проекты VK WorkSpace создается вебхук, который при событиях Добавление списания времени и Изменение списания времени отправляет данные об этих событиях во внешнюю систему. Пользователь внешней системы может в реальном времени видеть и учитывать списания пользователей Проекты VK WorkSpace, сделанные в том пространстве, для которого создан вебхук.

Доступ к разделу Вебхуки в настройках пространства выдается пользователям с разрешением Управление вебхуками.

По умолчанию разрешение Управление вебхуками включено для роли Администратор и отключено для ролей Пользователь и Гость.

Добавление вебхука

1. Войдите в систему, используя учетную запись, для которой подключено разрешение Управление вебхуками.
2. Перейдите в пространство, для которого вы хотите добавить вебхук.
3. Перейдите в настройки пространства и нажмите Вебхуки на панели слева.
4. Нажмите Добавить.
5. На открывшемся экране добавления вебхука заполните поля:
   • Название вебхука;
   • Описание вебхука;
   • URL (обязательное) — адрес во внешней системе, куда будет отправлен запрос с данными;
   • Токен (обязательное) — токен для работы с вебхуками, сформированный во внешней системе. Если внешняя система не предполагает использования токенов, введите в поле любое значение;
6. Выберите из списка одно или несколько событий, при наступлении которых будет срабатывать вебхук.
7. Добавьте пользовательский заголовок, который будет передаваться во внешнюю систему (опционально):
   1. Нажмите Добавить заголовок.
   2. Введите ключ и значение заголовка. Длина каждого параметра не может быть больше 2048 символов. Пара ключ-значение может использоваться для передачи во внешнюю систему какого-либо специфического параметра.
8. Настройте SSL-верификацию с помощью переключателя. По умолчанию SSL-верификация разрешена. Если необходимо отключить верификацию, переведите переключатель в неактивное положение.
9. Опционально. Нажмите Проверить в правом верхнем углу, а затем в раскрывшемся списке нажмите на название события, отправку данных которого вы хотите проверить. Результат проверки выводится в открывшемся окне, где указаны:
   • код ответа (200 для успешного завершения запроса);
   • тело основного запроса с параметрами и переменными;
   • тело запроса с передачей заголовков и метаданных.
10. Нажмите Добавить в правом верхнем углу.

Вебхук будет добавлен в систему и на экране Вебхуки будет отображена новая строка, включающая:

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

Активация и деактивация вебхука

1. Войдите в систему, используя учетную запись, для которой подключено разрешение Управление вебхуками.
2. Перейдите в пространство, вебхуками которого вы хотите управлять.
3. Перейдите в настройки пространства.
4. На открывшемся экране найдите в таблице нужный вебхук и переведите переключатель в столбце Активен в нужное положение.

Активное положение переключателя выделяется синим цветом.

Неактивные вебхуки не отправляют во внешнюю систему запрос при наступлении события.

Редактирование вебхука

1. Войдите в систему, используя учетную запись, для которой подключено разрешение Управление вебхуками.
2. Перейдите в пространство, вебхуками которого вы хотите управлять.
3. Перейдите в настройки пространства и нажмите Вебхуки на панели слева.
4. На открывшемся экране найдите в таблице нужный вебхук и нажмите на его название.
5. На открывшемся экране отредактируйте данные как указано в подразделе Добавление вебхука.
6. Нажмите Сохранить в правом верхнем углу.

Просмотр результатов выполнения вебхука

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

Журнал представлен в виде таблицы, которая содержит:

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

При нажатии на строку с событием открывается окно, в котором содержится:

• код ответа (200 для успешного завершения запроса);
• статус ответа — ОК при успешном завершении или название ошибки при неудачном;
• тело основного запроса с параметрами и переменными;
• тело запроса с передачей заголовков, токенов и других специфических данных.

??? note “Пример” Событие: добавление списания
Запрос json { "workitemId": "66030789-d986-4cbe-b2bc-a373d352ff10", "entryId": "35f98d2e-de65-4467-864d-dcce0e7ca2e6", "creationDate": "2024-11-04T14:52:49.8289869Z", "startDate": "2024-11-04T14:52:46.023Z", "duration": 28800, "description": null, "tenantId": "00000000-0000-0000-0000-000000000000", "eventId": "aaaaaaaa-0004-4001-aaaa-aaaaaaaaaaaa", "eventName": "TimeTrackingCreated", "eventType": "TimeTrackingCreated", "userId": "57edd357-b3b1-496f-b2c5-1d1bbbf7175e", "workspaceId": "01c7722d-a7ea-4bd9-aaf8-799fb6c7cd6f", "workspaceKey": "PIS" } Заголовки

```json
{
"x-Vk-Token": "a1d3a252-86e9-42f7-873a-702e61f5a066",
"x-Vk-Event-Id": "aaaaaaaa-0004-4001-aaaa-aaaaaaaaaaaa",
"x-Vk-Event-Name": "TimeTrackingCreated",
"traceparent": "00-e979a28161887095991267906fe8097d-74f461029ea50326-00"
}
```

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

Чтобы изменить дату и время:

1. Нажмите на поле.
2. Выберите новую дату и время из раскрывшегося календаря с часами или нажмите Сейчас, чтобы установить текущие дату и время.
3. Нажмите ОК.

Удаление вебхука

1. Войдите в систему, используя учетную запись, для которой подключено разрешение Управление вебхуками.
2. Перейдите в пространство, вебхуками которого вы хотите управлять.
3. Перейдите в настройки пространства и нажмите Вебхуки на панели слева.
4. На открывшемся экране найдите в таблице нужный вебхук и нажмите кнопку удаления в правой части строки.
5. Нажмите **Да, я хочу удалить вебхук.

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

Список событий вебхуков

Поля контекста события создания задачи

Поля контекста события изменения задачи

Поля контекста события создания или изменения статуса спринта

Поля контекста события добавления или изменения списания

Поля контекста события добавления и удаления задачи из элемента портфеля