Перейти к содержанию

Вебхуки

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

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

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

Пример

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

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

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

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

  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"
}
Заголовки 
{
"4": "TIMETRACKING",
"x-TeamStorm-Token": "a1d3a252-86e9-42f7-873a-702e61f5a066",
"x-TeamStorm-Event-Id": "aaaaaaaa-0004-4001-aaaa-aaaaaaaaaaaa",
"x-TeamStorm-Event-Name": "TimeTrackingCreated",
"traceparent": "00-e979a28161887095991267906fe8097d-74f461029ea50326-00"
}

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

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

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

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

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

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

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

Событие Описание события
WorkitemCreated Создание задачи
WorkitemStatusChanged Изменение статуса
WorkitemDescriptionChanged Изменение описания
WorkitemNameChanged Изменение имени
WorkitemUserAssigned Изменение ответственного
WorkitemParentChanged Изменение родительской задачи или папки
WorkitemStartDateChanged Изменение даты начала
WorkitemDueDateChanged Изменение даты выполнения
WorkitemAddedToPortfolioElement Добавление задачи в элемент портфеля
WorkitemDeletedFromPortfolioElement Удаление задачи из элемента портфеля
TimeTrackingCreated Добавление списания времени
TimeTrackingUpdated Редактирование списания времени
WorkitemWorkflowIdChanged Изменение процесса
WorkitemTypeChanged Изменение типа задачи
SprintCreated Создание спринта
WorkitemQueueIdChanged Изменение спринта
SprintStatusChanged Изменение статуса спринта
WorkitemEstimatedTimeChanged Изменение оценки в часах
WorkitemEstimatedStoryPointsChanged Изменение оценки в сторипоинтах
WorkitemProgressValueChanged Изменение значения прогресса
WorkitemAttributeChanged Изменение значения пользовательского атрибута

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

Поле Описание
workitemId Идентификатор созданной задачи
workitemKey Ключ созданной задачи
workitemName Название созданной задачи
workitemDescription Описание созданной задачи
workitemAssigneeId Идентификатор ответственного на задаче
workitemTypeId Идентификатор типа задачи
workitemCreationDate Дата создания задачи
workitemWorkflowId Идентификатор рабочего процесса задачи
workitemQueueId Идентификатор спринта
mentionedUserIds Список идентификаторов упоминаемых пользователей
tenantId Идентификатор тенанта
eventId Идентификатор события
eventName Название события
eventType Тип события
userId Идентификатор пользователя, инициировавшего событие
workspaceId Идентификатор пространства, в котором произошло событие
workspaceKey Ключ пространства, в котором произошло событие

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

Поле Описание
oldValue Старое значение измененного атрибута
newValue Новое значение измененного атрибута
workitemParentId Идентификатор родительской задачи или папки
workitemStatusId Идентификатор статуса задачи
workitemCreatedBy Идентификатор пользователя, создавшего задачу
workitemUpdatedBy Идентификатор пользователя, изменившего задачу
workitemUpdateDate Дата изменения задачи
workitemDueDate Дата выполнения
workitemEndDate Дата закрытия задачи
workitemStartDate Дата начала
workitemAttributesValues Значение атрибутов задачи
workitemProgressType Тип расчета прогресса
workitemProgressName Название метрики прогресса
workitemProgressValue Значение прогресса
workitemEstimatedTime Оценка во времени (в секундах)
workitemSpentTime Затраченное время (в секундах)
workitemLeftTime Оставшееся от оценки время (в секундах)
workitemEstimatedStoryPoints Оценка в сторипоинтах
workitemTicketTypeId Идентификатор типа заявки по которой создана задача.
workitemId Идентификатор созданной задачи
workitemKey Ключ созданной задачи
workitemName Название созданной задачи
workitemDescription Описание созданной задачи
workitemAssigneeId Идентификатор ответственного на задаче
workitemTypeId Идентификатор типа задачи
workitemCreationDate Дата создания задачи
workitemWorkflowId Идентификатор рабочего процесса задачи
workitemQueueId Идентификатор спринта
mentionedUserIds Список идентификаторов упоминаемых пользователей
tenantId Идентификатор тенанта
eventId Идентификатор события
eventName Название события
eventType Тип события
userId Идентификатор пользователя, инициировавшего событие
workspaceId Идентификатор пространства, в котором произошло событие
workspaceKey Ключ пространства, в котором произошло событие

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

Поле Описание
extensionId Идентификатор расширения Agile
sprintId Идентификатор спринта
sprintName Название спринта
sprintStatus Статус спринта
sprintStatus Статус спринта
tenantId Идентификатор тенанта
eventId Идентификатор события
eventName Название события
eventType Тип события
userId Идентификатор пользователя, инициировавшего событие
workspaceId Идентификатор пространства, в котором произошло событие
workspaceKey Ключ пространства, в котором произошло событие

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

Поле Описание
workitemId Идентификатор задачи, с которой связано списание
entryId Идентификатор списания
creationDate Дата добавления списания
startDate Дата списания
duration Время списания в секундах
description Описание списания
tenantId Идентификатор тенанта
eventId Идентификатор события
eventName Название события
eventType Тип события
userId Идентификатор пользователя, инициировавшего событие
workspaceId Идентификатор пространства, в котором произошло событие
workspaceKey Ключ пространства, в котором произошло событие

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

Поле Описание
workitemId Идентификатор задачи
portfolioElementId Идентификатор элемента портфеля
portfolioElementName Название элемента портфеля
portfolioElementStatusId Идентификатор статуса элемента портфеля
tenantId Идентификатор тенанта
eventId Идентификатор события
eventName Название события
eventType Тип события
userId Идентификатор пользователя, инициировавшего событие
workspaceId Идентификатор пространства, в котором произошло событие
workspaceKey Ключ пространства, в котором произошло событие