JIRA Webhook

---

Webhook

webhook是爲插件通過HTTP回調監聽產品內事件的標準機制。一個插件能夠在Atlassian Connect裝飾器中註冊一個用於監聽事件的webhook。

1 處理webhook事件

爲了能夠接收webhook事件，你的插件需要在它的JSON裝飾器中包含webhook模塊的聲明。這個聲明包含了插件用於接收webhook事件的相對網址。換句話說，應用會發送一個HTTP POST給該資源來作爲對應用事件的響應。處理POST的插件代碼應該處理該消息中主體部分的幾乎仍一個信息。每個發送給插件的webhook的POST也將會包含授權報頭來允許插件來對請求消息進行驗證。尤其是，JWT token能夠被發現在HTTP報頭的“Authentication”中。

注意：如果使用Aapache和mod_wsgi來提供文件給Django應用，授權報頭默認是被去除的。額外的配置要求保證授權報頭是可見的。

重要：一定要注意，webhook傳遞是不可靠的。當一個webhook事件被觸發，一個POST請求將會被髮送給對應的插件。如果這個時候插件掛掉了或者因爲網絡問題插件和Aatlassion應用通信異常，你將會無法接收到該事件。總的來說，webhook是可靠的，但是webhook的傳遞通常是不可靠的。

2 變量替換

Jira的webhook也提供了添加和替換url中的變量的方法。這與插件中的上下文參數很相似。

例如，當我們註冊一個包含${project.id}的url來監聽一個項目事件時，一個POST消息將會被髮送到包含${project.id}的地址，${project.id}的值可以根據被觸發事件的項目的ID確定。

3 過濾器

過濾器可以使webhook只對滿足特定條件的事件進行觸發。過濾器的值如何看上去準確，過濾器是否都可用，取決於事件類型。下面的章節會介紹所有的可能性。

3.1 JQL

問題相關的時間可以用JQL過濾。webhook僅僅對滿足JQL查詢條件的問題的事件進行觸發。JQL查詢（“project = TEST AND fixVersion = future”）可以被放進“filter”屬性中。

JQL過濾器僅支持以下事件類型：

• jira:issue_created
• jira:issue_deleted
• jira:issue_updated
• comment_created
• comment_updated
• comment_deleted

3.2 Webhook 事件類型

下面是所有可用的事件類型：

3.2.1 插件和系統事件

- connect_addon_disabled
- connect_addon_enabled

3.2.2 問題時間

- jira:issue_created
- jira:issue_deleted
- jira:issue_updated

上下文參數有${project.id}, ${project.key}, ${issue.key}, ${issue.id}

3.2.3 版本事件

- jira:version_created
- jira:version_deleted
- jira:version_merged
- jira:version_updated
- jira:version_moved
- jira:version_released
- jira:version_unreleased

上下文參數有${project.id}, ${project.key}, ${version.id}
version_merged事件的特殊上下文參數是${mergedVersion.id}

3.2.4 項目事件

- project_created
- project_updated
- project_deleted

上下文參數有${project.id}, ${project.key}

3.2.5 用戶事件

- user_created
- user_deleted
- user_updated

上下文參數有：${modifiedUser.name}, ${modifiedUser.key}

3.2.6 特徵狀態事件

- option_voting_changed
- option_watching_changed
- option_unassigned_issues_changed
- option_subtasks_changed
- option_attachments_changed
- option_issuelinks_changed
- option_timetracking_changed

3.2.7 備註事件

- comment_created
- comment_updated
- comment_deleted

3.2.8 Confluence webhook事件

- attachment_created
- attachment_removed
- attachment_restored
- attachment_trashed
- attachment_updated
- attachment_viewed
- blog_created
- blog_removed
- blog_restored
- blog_trashed
- blog_updated
- blog_viewed
- blueprint_page_created
- comment_created
- comment_removed
- comment_updated
- connect_addon_disabled
- connect_addon_enabled
- content_created
- content_restored
- content_trashed
- content_updated
- content_permissions_updated
- group_created
- group_removed
- label_added
- label_created
- label_deleted
- label_removed
- Login
- login_failed
- Logout
- page_children_reordered
- page_created
- page_moved
- page_removed
- page_restored
- page_trashed
- page_updated
- page_viewed
- relation_created
- relation_deleted
- search_performed
- space_created
- space_logo_updated
- space_permissions_updated
- space_removed
- space_updated
- theme_enabled
- user_created
- user_deactivated
- user_followed
- user_reactivated
- user_removed

3.3 例程請求

 POST /jira-issue_created?user_id=admin&user_key=admin HTTP/1.1
 Authorization: JWT ...
 Atlassian-Connect-Version: x.x
 Content-Type: application/json
 {
   timestamp: 1426661049725,
   webhookEvent: 'jira:issue_created',
   ...
 }

3.4 例程響應

JIRA 問題相關的Webhook事件結構

{
   "timestamp"
   "event"
   "user": {
     // See User shape in the linked document
   },
   "issue": {
     // See Issue shape in the linked document
   },
   "changelog" : {
     // See Changelog shape in the linked document
   },
   "comment" : {
     // See Comment shape in in the linked document
   }
 }

3.4.1 Confluence 頁面創建

{
   "page": {
     "spaceKey": "~admin",
     "modificationDate": 1471926079631,
     "creatorKey": "ff80808154510724015451074c160001",
     "creatorName": "admin",
     "lastModifierKey": "ff80808154510724015451074c160001",
     "self": "https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
     "lastModifierName": "admin",
     "id": 16777227,
     "title": "Some random test page",
     "creationDate": 1471926079631,
     "version": 1
   },
   "user": "admin",
   "userKey": "ff80808154510724015451074c160001",
   "timestamp": 1471926079645,
   "username": "admin"
 }

3.4.2 Confluence備註創建

 {
   "comment": {
     "spaceKey": "~admin",
     "parent": {
       "spaceKey": "~admin",
       "modificationDate": 1471926079631,
       "creatorKey": "ff80808154510724015451074c160001",
       "creatorName": "admin",
       "lastModifierKey": "ff80808154510724015451074c160001",
       "self": "https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page",
       "lastModifierName": "admin",
       "id": 16777227,
       "title": "Some random test page",
       "creationDate": 1471926079631,
       "version": 1
     },
     "modificationDate": 1471926091465,
     "creatorKey": "ff80808154510724015451074c160001",
     "creatorName": "admin",
     "lastModifierKey": "ff80808154510724015451074c160001",
     "self": "https://cloud-development-environment/wiki/display/~admin/Some+random+test+page?focusedCommentId=16777228#comment-16777228",
     "lastModifierName": "admin",
     "id": 16777228,
     "creationDate": 1471926091465,
     "version": 1
   },
   "user": "admin",
   "userKey": "ff80808154510724015451074c160001",
   "timestamp": 1471926091468,
   "username": "admin"
 }

4 檢查webhook內容

Pending… …