Вебхуки

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

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

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

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

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

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 для успешного завершения запроса);
• статус ответа — ОК при успешном завершении или название ошибки при неудачном;
• тело основного запроса с параметрами и переменными;
• тело запроса с передачей заголовков, токенов и других специфических данных.

Пример

Событие — Добавление списания:

 
## Запрос    {    "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"    }    ## Заголовки    {    "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. Нажмите Да, я хочу удалить вебхук.

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