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… …