1. Главная
  2. СТРОИТЕЛЬНЫЕ БЛОКИ
  3. Webhooks

Webhooks

Webhook - это определяемый пользователем обратный вызов через HTTP. Вы можете использовать веб-ссылки Jira для уведомления своего приложения или веб-приложения, когда в Jira происходят определенные события. Например, вы можете предупредить свое удаленное приложение при обновлении задачи или при запуске спринта. Использование webhook для этого означает, что вашему удаленному приложению не нужно периодически опрашиваемым Jira (через API REST), чтобы определить, произошли ли изменения.

Обзор

Webhooks в Jira определяется следующей информацией, которую вам необходимо предоставить при регистрации (то есть создании) нового webhook:

  • Имя созданного webhook (например, «Webhook для моего удаленного приложения»).
  • URL-адрес, по которому должен быть отправлен обратный вызов.
  • Объем webhook, либо «все задачи», либо ограниченный набор задач, заданных JQL («project = TEST и fixVersion = future»).
  • События, отправляемые по URL-адресу, либо «все события», либо определенный набор событий.

 

Простой webhook может выглядеть так:

Имя: "Мой простой webhook"

URL: www.myremoteapp.com/webhookreceiver

Сфера применения: все задачи

События: все события задач

Более сложный webhook может выглядеть следующим образом:

Название: «Немного более продвинутый webhook»

URL: www.myremoteapp.com/webhookreceiver

Область действия: Project = JRA AND fixVersion IN ("6.4", "7.0")

События: задача обновлена, задача создана

Регистрация webhook

Чтобы зарегистрировать webhook, вы можете использовать любой из следующих способов:

  • Административная консоль Jira.
  • Jira REST API (обратите внимание, что пользователь должен иметь глобальное разрешение администратора Jira).

Регистрация webhook через консоль администратора Jira

  1. Перейдите в консоль администратора Jira> System> Webhooks (в разделе Advanced). Вы также можете использовать быстрый поиск (сочетание клавиш есть.), затем наберите «webhooks».
  2. Нажмите Создать webhook.
  3. В форме, которая показана, введите данные для нового webhook. Дополнительные сведения об этом см. в разделе Настройка webhook позже на этой странице.
  4. Чтобы зарегистрировать свой веб-сайт, нажмите «Создать».

РИСУНОК

Операции с webhook через JRE REST API

Регистрация webhook

Чтобы зарегистрировать webhook через REST, выполните POST в формате JSON по следующему URL-адресу:

<JIRA_URL> /rest/webhooks/1.0/webhook


{
"name": "my first webhook via rest",
"url": "http://www.example.com/webhooks",
"events": [
  "jira:issue_created",
  "jira:issue_updated"
],
"filters": {
	"issue-related-events-section": "Project = JRA AND resolution = Fixed"
},
"excludeBody" : false
}

Ответ вернет webhook в JSON с дополнительной информацией, включая пользователя, создавшего webhook, созданную временную метку и т. д.

Отменить регистрацию webhook

Чтобы отменить регистрацию (то есть удалить) webhook через REST, выполните DELETE по следующему URL-адресу:

<JIRA_URL>/rest/webhooks/1.0/webhook/{id of the webhook}

Следующее удалит webhook с идентификатором 70:


curl --user username:password -X DELETE -H "Content-Type: application/json" /rest/webhooks/1.0/webhook/70

Запросить(Query) webhook

Чтобы запросить webhook через REST:

  • Чтобы получить все веб-ссылки для экземпляра Jira, выполните GET по следующему URL-адресу:

<JIRA_URL>/rest/webhooks/1.0/webhook.


curl --user username:password -X GET -H "Content-Type: application/json" /rest/webhooks/1.0/webhook
  • Чтобы получить конкретный webhook по его идентификатору, выполните GET по следующему URL-адресу:

<JIRA_URL> /rest/webhooks/1.0/webhook/ <webhook ID>

Следующее получит webhook с идентификатором 72:


curl --user username:password -X GET -H "Content-Type: application/json" /rest/webhooks/1.0/webhook/72

Редактировать webhook

Чтобы отредактировать webhook, выполните метод PUT по следующему URL-адресу:

<JIRA_URL> /rest/webhooks/1.0/webhook/ {id of the webhook}


{
"name": "my first webhook via rest",
"url": "http://www.example.com/webhooks",
"events": [
  "jira:issue_created",
  "jira:issue_updated"
],
"filters": {
	"issue-related-events-section": "Project = JRA AND resolution = Fixed"
},
"excludeBody" : false
}

Настройка webhook

Информация в этом разделе поможет вам настроить webhook, создаете ли вы новый или модифицируете существующий.

Регистрация событий для webhooks

Следующие события доступны для webhooks Jira. Строка в круглых скобках - это имя webhookEvent в ответе.

Задачи, связанные с:

  • Задача ...
    • создано (jira: issue_created)
    • обновлено (jira: issue_updated)
    • удалено (jira: issue_deleted)
    • Изменен рабочий журнал (jira: worklog_updated)

Примечание. Это событие срабатывает, если рабочий журнал обновлен или удален

  • Ссылка на задачу ...
    • создано (issuelink_created)
    • удалено (* issuelink_deleted)

Примечание. Доступно в Jira 7.5 и более поздних версиях.

  • Журнал событий...
    • создано (worklog_created)
    • обновлено (worklog_updated)
    • удалено (worklog_deleted)
  • Комментарий…
  • Создано (comment_created)
  • обновлено (comment_updated)
  • удалено (comment_deleted)

Примечание. Доступно в Jira 7.1 или более поздней версии.

Связанные с проектом:

  • Проект ...
    • создано (project_created)
    • обновлено (project_updated)
    • удалено (project_deleted)
  • Версия…

 

  • выпущен (jira: version_released)
  • unreleased (jira: version_unreleased)
  • создано (jira: version_created)
  • перемещен (jira: version_moved)
  • обновлено (jira: version_updated)
  • удалено (jira: version_deleted)
  • объединено (jira: version_deleted)

Примечание. Это одно и то же имя webhookEvent как «удаленное» событие, но ответ будет включать свойство mergedTo

Связанные с пользователем:

  • Пользователь ...
  • Создано (user_created)
  • обновлено (user_updated)
  • удаленный (user_deleted)

 

Связанные с конфигурацией Jira:

  • Функция включена / отключена ...
    • голосование (option_voting_changed)
    • наблюдение(option_watching_changed)
    • неназначенные задачи (option_unassigned_issues_changed)
    • подзадачи (subtasks)(option_subtasks_changed)
    • вложения (option_attachments_changed)
    • ссылки задач (option_issuelinks_changed)
    • отслеживание времени (option_timetracking_changed)

Связанное с программным обеспечением Jira:

  • Sprint ...
    • создано (sprint_created)
    • удалено (sprint_deleted)
    • обновлено (sprint_updated)
    • началось (sprint_started)
    • закрыто (sprint_closed)
  • Доска...
    • создано (board_created)
    • обновлено (board_updated)
    • удалено (board_deleted)
    • изменена конфигурация (board_configuration_changed)

Выбор событий для вашего webhook

Если вы не знаете, для каких событий регистрировать ваш webhook, то самый простой способ - зарегистрировать свой webhook для всех событий для соответствующей сущности (например, все связанные с событиями события). Тогда вам не нужно будет обновлять webhook, если вам нужно будет обрабатывать эти события в будущем; вы можете просто добавить код в приложение или веб-приложение, когда вы хотите реагировать на них.

Ограничение ваших событий до подмножества задач через JQL

Если вы хотите, чтобы события вашего webhook запускались для определенного набора задач, вы можете указать JQL-запрос (query) в своем webhook для отправки только событий, вызванных соответствующими задачами. Например, используя JQL, вы можете регистрировать для удаленные события задач в задачах в проекте Test («TEST»), которые отмечены компонентом «Производительность».

РИСУНОК

Хотя JQL, который использует стандартные поля Jira, очень эффективен, некоторые пользовательские поля из-за их реализации могут потребовать несколько секунд для запроса(query). Это следует учитывать при использовании JQL для webhook, поскольку запрос(query) будет запускаться с каждым событием.

Переменная замещения в URL-адресе webhook

Вы можете добавлять переменные в URL-адрес webhook при создании или обновлении webhook. Переменные следующие:

  • ${board.id}
  • ${issue.id}
  • ${issue.key}
  • ${mergedVersion.id}
  • ${modifiedUser.key}
  • ${modifiedUser.name}
  • ${project.id}
  • ${project.key}
  • ${sprint.id}
  • ${version.id}

Вы можете использовать эти переменные для динамического вставки значения текущего ключа задачи, идентификатора спринта, ключа проекта и т. д. в URL-адрес webhook  при его запуске.

Например, вы указали URL-адрес своего webhook  с переменной $ {issue.key}, как это:


http://jira.example.com/webhook/${issue.key}

Если задача с ключом EXA-1 запускает webhook, тогда URL-адрес, который будет использоваться:


http://service.example.com/webhook/EXA-1

Добавление webhook в качестве функции отправки в рабочий процесс

Webhooks можно подключить как post функцию рабочего процесса. Это упрощает запуск webhook, когда задача приводит к переходу рабочего процесса. Например, когда он отклоняется от QA или когда он разрешается.

Чтобы добавить webhook в качестве функции отправки в рабочий процесс:

  1. Перейдите в конфигурацию рабочего процесса и выберите нужный переход в дизайнере рабочего процесса. Дополнительные сведения см. в разделе Работа с рабочими процессами.
  2. Нажмите функции Post, а затем «Добавить post функцию».
  3. Выберите Запустить Webhook из списка post функций и нажмите «Добавить».
  4. Выберите нужный webhook из списка webhooks и нажмите «Добавить», чтобы добавить webhook в качестве функции post.

Заметки:

  • Если выбранный webhook также настроен на прослушивание событий, webhook будет запускаться дважды: один раз для события и один раз для перехода рабочего процесса. По этой причине вы всегда должны удалять выбор всех событий с экрана администратора webhook.
  • Если webhook связан с функцией post, вы не сможете удалить веб-сайт. Вы должны сначала отключить его от постфункции.

Выполнение webhook

Webhooks будет запущен без определенного пользовательского контекста. Например, все задачи будут доступны для webhook, а не для того, чтобы иметь их охваченых  одним пользователем. (Обратите внимание, что URL-адрес также будет содержать пользовательские параметры в форме: user_id = (u'sysadmin ',)&user_key = (u'sysadmin',), добавленные в конце.)

По умолчанию webhook отправляет запрос с обратным вызовом JSON при его запуске. Если вы не хотите, чтобы тело JSON было отправлено, вам нужно выбрать «Исключить» тело при настройке webhook.

На высоком уровне каждый обратный вызов содержит идентификатор webhookEvent, метку времени timestamp и информацию об сущности, связанной с событием (например, задача, проект, доска и т. д.). Обратные вызовы могут содержать дополнительную информацию в зависимости от типа связанного с ней события. В качестве примера описывается структура обратного вызова для события, связанного с задачей.

Пример: обратный вызов для связанного с задачей события

Обратный вызов для связанного с задачей события структурирован следующим образом:


{
    "timestamp"
    "event"
    "user": {
               --> See User shape in table below
    },
    "issue": {
               --> See Issue shape in table below
    },
    "changelog" : {
               --> See Changelog shape in table below    
    },
    "comment" : {
               --> See Comment shape in table below  
    }
}

Форма задачи

  • Такая же форма возвращается из JRE REST API, когда задача извлекается без НИКАКИХ параметров расширения.
  • REST API docs: Задача: получить задачу.
  • Пример: JRA-2000.
  • Задача всегда присутствует в POST webhook.

 

Форма пользователя

  • Такая же форма возвращается из Jira REST API, когда пользователь извлекается, но без активных элементов часового пояса или групп.
    • Форма возвращаемого пользователя является конденсированной формой из обычного пользовательского API в REST, но аналогична тому, что возвращается, когда пользователь встроен в другой ответ.
    • Для получения полной информации о пользователе используйте API-интерфейс JRE REST и запрос(query) с именем пользователя.
  • REST API docs: Пользователь: Получить пользователя.
  • Пример: Пример для «username = brollins».
  • Пользователь всегда присутствует в POST веб-хостинга для событий задачи.

Форма журнала изменений

  • Массив элементов изменения, с одной записью для каждого поля, которое было изменено.
  • Журнал изменений предоставляется только для события issue_updated.
  • Это похоже на формат журнала изменений, который вы могли бы получить из задачи Jira, но без пользователя (потому что это уже находится в JSON) и без созданной временной метки (потому что это тоже уже в JSON для события webhook).

"changelog": {
        "items": [
            {
                "toString": "A new summary.",
                "to": null,
                "fromString": "What is going on here?????",
                "from": null,
                "fieldtype": "jira",
                "field": "summary"
            },
            {
                "toString": "New Feature",
                "to": "2",
                "fromString": "Improvement",
                "from": "4",
                "fieldtype": "jira",
                "field": "issuetype"
            },
        ],
        "id": 10124
}

Форма комментария

  • Такая же форма возвращается из Jira REST API при получении комментария.
  • REST API docs: Задача: Получить комментарии.
  • Пример: комментарий.
  • Комментарий будет предоставлен, если комментарий был предоставлен с изменением.

{
    "id": 2,
    "timestamp": 1525698237764,
    "issue": {
        "id":"99291",
        "self":"https://jira.atlassian.com/rest/api/2/issue/99291",
        "key":"JRA-20002",
        "fields":{
            "summary":"I feel the need for speed",
            "created":"2009-12-16T23:46:10.612-0600",
            "description":"Make the issue nav load 10x faster",
            "labels":["UI", "dialogue", "move"],
            "priority": "Minor"
        }
    },
    "user": {
        "self":"https://jira.atlassian.com/rest/api/2/user?username=brollins",
        "name":"brollins",
        "key":"brollins",
        "emailAddress":"bryansemail at atlassian dot com",
        "avatarUrls":{
            "16x16":"https://jira.atlassian.com/secure/useravatar?size=small&avatarId=10605",
            "48x48":"https://jira.atlassian.com/secure/useravatar?avatarId=10605"
        },
        "displayName":"Bryan Rollins [Atlassian]",
        "active" : "true"
    },
    "changelog": {
        "items": [
            {
                "toString": "A new summary.",
                "to": null,
                "fromString": "What is going on here?????",
                "from": null,
                "fieldtype": "jira",
                "field": "summary"
            },
            {
                "toString": "New Feature",
                "to": "2",
                "fromString": "Improvement",
                "from": "4",
                "fieldtype": "jira",
                "field": "issuetype"
            }
        ],
        "id": 10124
    },
    "comment" : {
        "self":"https://jira.atlassian.com/rest/api/2/issue/10148/comment/252789",
        "id":"252789",
        "author":{
            "self":"https://jira.atlassian.com/rest/api/2/user?username=brollins",
            "name":"brollins",
            "emailAddress":"bryansemail@atlassian.com",
            "avatarUrls":{
                "16x16":"https://jira.atlassian.com/secure/useravatar?size=small&avatarId=10605",
                "48x48":"https://jira.atlassian.com/secure/useravatar?avatarId=10605"
            },
            "displayName":"Bryan Rollins [Atlassian]",
            "active":true
        },
        "body":"Just in time for AtlasCamp!",
        "updateAuthor":{
            "self":"https://jira.atlassian.com/rest/api/2/user?username=brollins",
            "name":"brollins",
            "emailAddress":"brollins@atlassian.com",
            "avatarUrls":{
                "16x16":"https://jira.atlassian.com/secure/useravatar?size=small&avatarId=10605",
                "48x48":"https://jira.atlassian.com/secure/useravatar?avatarId=10605"
            },
            "displayName":"Bryan Rollins [Atlassian]",
            "active":true
        },
        "created":"2011-06-07T10:31:26.805-0500",
        "updated":"2011-06-07T10:31:26.805-0500"
    },  
    "webhookEvent": "jira:issue_updated"
}

Коды ответов

Если webhook запускается успешно, возвращается код ответа 200. Все другие коды ответов следует рассматривать как неудачную попытку запуска webhook.

Расширенные темы

Что произойдет, если удаленная система не «поймает» POST webhook?

В этом случае Jira зарегистрирует ошибку в файле журнала atlassian-jira.log.

В настоящее время есть ошибка(bug), которая заставляет Jira вести себя по-другому. Вы можете просмотреть задачу JRASERVER-41388 для получения обновлений.

Какие версии Jira поддерживают webhooks?

Jira 5.2 и более поздние версии поддерживают webhooks. Если вы используете Jira 5.2.x, имейте в виду следующие ограничения:

  • Если вы используете Jira 5.2.1 или более раннюю версию, при использовании JQL с webhooks существуют две известные задачи и ограничения:
    • Функция currentUser () работает не так, как ожидалось.
    • Если JQL-запрос (query) фильтрует поле, которое часто изменяется, оно может не возвращать желаемые результаты (описание этой проблемы см. в примечаниях к обновлению 5.2). Это означает, что вы не должны писать webhook, который использует выражение JQL для поиска определенного изменения состояния.

               Например, если вы хотите, чтобы POST webhook в любое время, когда задача была изменена, чтобы иметь приоритет блокировки, вы не должны включать «Приоритет = Блокировка» в предложение JQL, но оставить приоритет и фильтр для тех событий, в которых был изменен приоритет к Блокатору на принимающей стороне webhook.

  • Если вы используете Jira 5.2.2 или ранее, есть известные задачи при использовании JQL с webhooks:
    • Замена переменной $ {issue.key} не работает в webhook, когда webhook используется в post функции рабочего процесса. Обратите внимание, что замена переменной $ {issue.key} работает, когда событие задачи запускает

Дополнительные ресурсы

Сообщения в блоге Atlassian:

  • Jira Webhooks: оставьте нам свой URL, и мы перезвоним вам.
  • Webhooks Deep Dive: уведомлять клиента через SMS, когда их запрос (request) на обслуживание требует внимания.

Известные вопросы

  • Post функции webhooks не срабатывают, если они добавлены в переход рабочего процесса "Создать задачу". Мы рекомендуем вместо этого вам настроить web hook, чтобы активировать событие issue_created.
  • Фильтр JQL для web hook работает некорректно при запуске событий Comment (Комментарий) или Worklog (Рабочий журнал). См. Отчет: jira.atlassian.com/browse/JRA-59980. В качестве обходного пути вы можете использовать событие "Обновление задачи".

По материалам Atlassian JIRA  Server Developer Webhooks