v2.116.0 -支持 Webhook 通知

更新时间：20200305

更新内容：

私有部署支持开启插件系统；
支持添加、管理、配置、启用监听器（webhook模式）

使用指南:(功能介绍/使用场景/操作指引)

在某些情况下除了 ONES 系统通知方式以外，用户对于外部事件的通知，支持通过 Webhook 的方式，用户在提供了钩子地址进行配置后，即可在第三方获取 ONES 的系统消息。例如：应用想要获取新增的工作或状态变更，可以通过 Webhook 接收通知消息。

一、使用方法

进入团队配置中心 > 外部通知 - 监听器，即可配置监听器名称、发送模式、URL、设置监听事件和范围，测试成功并保存后，即可在第三方进行监听。

仅限已开启插件系统的私有部署版本，未启用 Webhook 的用户可联系我们服务人员进行升级。

二、Webhook 响应机制

ONES 将系统事件的参数，通过 HTTP 协议以 POST 方式通知指定的 URL。在接收到 ONES 的 Webhook 请求后，若因为网络不佳等情况 5 秒内未返回消息 ID 的状态码，系统会认为通知失败，启用重传机制

重传机制：每条消息至多重发 3 次，当系统 30分钟未检测到任何应答（期间系统每 5 分钟发送一次心跳消息），则判定对端的 Web 服务已失效，将停用 Webhook，用户可在配置界面手动重启。

三、Webhook 消息字段说明

消息交互方式分为两种：①系统通知；②心跳信息

用户无论是收到的系统通知，还是心跳消息，都需要返回其 ID。如果未收到返回消息，则判定当前消息发送失败。
接收通知消息的服务可以按照需要继续处理，心跳消息可以直接应答后抛弃。通知消息和心跳消息都是 json 标准的字符串。
我们在消息中提供了部分描述信息，以便于用户的使用。根据这些描述信息，用户可以直接得到一个可读性高的消息（与我们在微信或者 ONES 网页右上角收到的通知一样），而不需要根据某些 ID 去查询其对应的值。

{
    "id": "hhqS4Wa3UQYJeHZv"
}

{
    "id": "SWzhDqzxDDzgsJPB",
    "messages": [
        {
            "from_user": {
                "uuid": "6ZpgEzkk",
                "name": "贝加庞克"
            },
            "to_users": [],
            "title": "[onePiece]双方各被污染",
            "desc": "贝加庞克 将属性「状态」修改为「已计划」",
            "url": "https://xxxxxxx/#/team/BDfDqJU7/project/6ZpgEzkkmkvOVIU6/issue_type/GwNxpqQh/task/6ZpgEzkkUmmWMLeg",
            "task_uuid": "6ZpgEzkkUmmWMLeg",
            "issue_type_uuid": "GwNxpqQh",
            "issue_type_name": "需求",
            "event_type": "update_task_status",
            "event_name": "更新任务状态",
            "raw_message": {
                "uuid": "P6KGV72t",
                "team_uuid": "BDfDqJU7",
                "ref_type": "project",
                "ref_id": "6ZpgEzkkmkvOVIU6",
                "type": "system",
                "from": "BOT",
                "to": "6ZpgEzkkmkvOVIU6",
                "send_time": 1583152234311552,
                "subject_type": "user",
                "subject_id": "6ZpgEzkk",
                "action": "update",
                "object_type": "task",
                "object_id": "6ZpgEzkkUmmWMLeg",
                "object_name": "双方各被污染",
                "object_attr": "field",
                "old_value": "SriNNDVw",
                "new_value": "FXapje9B",
                "ext": {
                    "field_name": "状态",
                    "field_type": 12,
                    "field_uuid": "field005",
                    "new_option": {
                        "name": "已计划",
                        "uuid": "FXapje9B"
                    },
                    "new_value": "",
                    "old_option": {
                        "name": "进行中",
                        "uuid": "SriNNDVw"
                    },
                    "old_value": "",
                    "parent_message_uuid": "FBRsgsj3"
                },
                "is_can_show_richtext_diff": false
            }
        }
    ]
}

直接以字符串写入应答的消息体

hhqS4Wa3UQYJeHZv

事件

字段名

类型

说明

消息类型

string

消息体唯一标识 16位

消息类型

messages

[]message

消息体数组(目前消息推送只支持推送单条消息)

Message

from_user

user

消息来源

Message

to_users

[]user

ONES 体统内的配置的消息通知列表

Message

title

string

消息标题：格式 [团队名称]工作项名称

Message

desc

string

消息描述格式：who [do_what]

Message

url

string

工作项 url 地址

Message

task_uuid

string

工作项UUID

Message

issue_type_uuid

string

工作项类型UUID

Message

issue_type_name

string

作项类型名称

Message

event_type

string

事件类型

Message

event_name

string

事件名称

Message

raw_message

raw

ONES 系统中消息体

User

uuid

string

用户UUID

User

name

string

用户名称

Raw

uuid

string

message uuid

Raw

team_uuid

string

团队uuid

Raw

ref_type

string

消息引用类型： task：工作项 project：项目

Raw

ref_id

string

消息引用类型的uuid：如果"ref_type"是"task"的话，那么"ref_id"的值就是工作项uuid 如果"ref_type"是"project"的话，那么"ref_id"的值就是项目uuid

Raw

type

string

消息类型： discussion：评论类型动态 system：系统类型动态

Raw

from

string

谁发送的消息： BOT：代表系统

Raw

string

操作的实体：某个工作项或者某个项目

Raw

send_time

int64

发送时间

Raw

text

string

当"type"为"discussion"才有，评论的内容

Raw

is_can_show_richtext_diff

bool

是否能查看工作项描述的diff

Raw

subject_type

string

一般值为"user"

Raw

subject_id

string

操作人uuid

Raw

action

string

操作类型： add：新增 update：更新 delete:删除 move:移动 copy:复制

Raw

object_type

string

消息实体uuid

Raw

object_name

string

消息实体名称

Raw

object_attr

string

消息实体属性

Raw

new_value

string

更新后的值

Raw

ext

修改数据说明

Ext

field_uuid

string

属性UUID

Ext

field_name

string

属性名称，omitempty

Ext

field_type

int

属性类型

Ext

old_value

string

属性旧值

Ext

new_value

string

属性新值

Ext

old_option

desc

旧属性项，omitempty

Ext

new_option

desc

新属性项，omitempty

Ext

new_multi_option

[]desc

旧属性项列表，omitempty

Ext

old_multi_option

[]desc

新属性项列表，omitempty

Ext

batch_action

string

批处理动作

Ext

parent_message_uuid

string

主消息UUID

Ext

trigger_task_uuid

string

触发工作项UUID

Ext

trigger_task_title

string

触发工作项标题

Desc

uuid

string

UUID

Desc

name

string

名称

上一页v2.117.0-工作项批量关联用例及执行结果下一页v2.113.0- 重新绑定企业微信

最后更新于3年前