webhook 配置

webhook 是 ONES 系统的外部事件通知机制的实现。用户提供 webhook 钩子的地址，并且实现简单的消息应答，就可以使用 webhook 来获取系统中发生的事件的通知
要使用我们的 webhook 通知，需要提供一个 http 服务并实现一个 post 接口。此接口需要在收到消息后返回一个确认消息。若收不到返回的确认消息，我们的 webhook 将尝试进行重发。在一定时间内若收不到任何确认，则不再发送通知消息，并将自己的状态设置为未启用。此时，需要在配置页面手动重新启用后，webhook 才能正常工作
关于消息重传与停止/重新发送的技术细节，请参考消息重传机制 ONES webhook 是团队级别的功能

配置参数

配置项	类型	示例	描述
enable_webhook	boolean	true	是否开启TLS，建议开启

操作步骤

ONES 配置开启 webhook

修改配置

登陆 ONES 服务器，进入当前运行中实例的安装目录

sudo cd /data/ones/pkg/ones-example-3.14.xxxxx

修改<enable_webhook>配置的值为 true

./json-util -config config.json -operator add -key enable_webhook -valtype bool -value true

重启容器

注意：执行以下命令将造成 ONES 服务暂时不可用

containerID=$(docker ps |grep $(./json-util -config config.json -operator select -key deploy_name) | grep '0.0.0.0:'$(./json-util -operator select -key port -config ./config.json)'->' | awk '{print $1}')
./onesconfigure update $containerID -r

当观察到如下输出，则重启已经完成。稍等几分钟后 ONES 服务将可以正常访问

[root@localhost ones-example-3.14.xxxxx]# containerID=$(docker ps |grep $(./json-util -config config.json -operator select -key deploy_name) | grep '0.0.0.0:'$(./json-util -operator select -key port -config ./config.json)'->' | awk '{print $1}')
[root@localhost ones-example-3.14.xxxxx]# ./onesconfigure update $containerID -r
[INFO] 2023/05/30 10:36:07 WARNING: key 'InternalBaseUrl' not exist in config file '/data/conf/options.json'
[INFO] 2023/05/30 10:36:07 WARNING: key 'enable_automation' not exist in config file '/data/conf/options.json'
[INFO] 2023/05/30 10:36:07 WARNING: key 'ConfluenceBackMaxSize' not exist in config file '/data/conf/options.json'
[INFO] 2023/05/30 10:36:07 WARNING: key 'EnableModifyLoginPageLogo' not exist in config file '/usr/local/ones-ai-project-api/conf/config.json'
[WARN] 2023/05/30 10:36:07 update apps
[INFO] 2023/05/30 10:36:10 restart container...
[INFO] 2023/05/30 10:36:21 restart container success, container_id=f8caed932bff

验证

重启完成并稍等几分钟后，登录 ONES 系统，进入 「团队配置中心」-> 「外部通知」-> 「监听器」页面，能正常创建监听器则正常

webhook 接收器端信息

要使用我们的 webhook通知，需要提供一个 HTTP 服务以及一个POST接口，此接口需要在收到消息后返回一个确认消息。若收不到返回的确认消息，我们的 Webhook 将尝试进行重发。在一定时间内若收不到任何确认，则不再发送通知消息，并将自己的状态设置为未启用。此时，需要在配置页面手动重新启用后，Webhook 才能正常工作。

消息重传机制

用户需要在其钩子 api 上实现简单的消息应答协议。用户的 webhook 钩子收到消息后，需要将消息中的 ID 返回，这是为了让我们的消息尽可能送达。通过获取送达的消息的 ID，我们可以实现在网络环境不佳导致消息未送达时的消息重发。

目前我们的重试策略是：5 秒内未收到应答即重发，每个消息最大重发数量是 3 次。

若 webhook 在一定的时间（30 分钟）内，未能收到任意一笔消息的应答（系统没有产生通知时，我们会每 5 分钟发送一次心跳消息），我们认为对端的 web 服务已经失效，将停止发送通知。一旦发生这种情况， 则需要用户手动的在配置页面重新启用此 webhook。

消息类型

我们将发送两种消息:

  系统产生的通知；

  用于定时检测接口有效性的心跳消息；

用户无论是收到的系统通知，还是心跳消息，都需要返回其 ID。如果未收到返回消息，则判定当前消息发送失败。

接收通知消息的服务可以按照需要继续处理，心跳消息可以直接应答后抛弃。通知消息和心跳消息都是 json 标准的字符串。

我们在消息中提供了部分描述信息，以便于用户的使用。根据这些描述信息，用户可以直接得到一个可读性高的消息（与我们在微信或者 ONES 网页右上角收到的通知一样），而不需要根据某些 ID 去查询其对应的值。

消息示例

{
  "id": "SWzhDqzxDDzgsJPB",
  "messages": [
    {
      "from_user": {
        "uuid": "6ZpgEzkk",
        "name": "Lyon"
      },
      "to_users": [],
      "title": "[onePiece]title a",
      "desc": "Lyon modify attribute from status to planned",
      "url": "https://xxxxxxx/#/team/BDfDqJU7/project/6ZpgEzkkmkvOVIU6/issue_type/GwNxpqQh/task/6ZpgEzkkUmmWMLeg",
      "task_uuid": "6ZpgEzkkUmmWMLeg",
      "issue_type_uuid": "GwNxpqQh",
      "issue_type_name": "Requirement",
      "event_type": "update_task_status",
      "event_name": "update task status",
      "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": "title a",
        "object_attr": "field",
        "old_value": "SriNNDVw",
        "new_value": "FXapje9B",
        "ext": {
          "field_name": "status",
          "field_type": 12,
          "field_uuid": "field005",
          "new_option": {
            "name": "planned",
            "uuid": "FXapje9B"
          },
          "new_value": "",
          "old_option": {
            "name": "in progress",
            "uuid": "SriNNDVw"
          },
          "old_value": "",
          "parent_message_uuid": "FBRsgsj3"
        },
        "is_can_show_richtext_diff": false
      }
    }
  ]
}

心跳消息

{
  "id": "hhqS4Wa3UQYJeHZv"
}

应答消息

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

hhqS4Wa3UQYJeHZv

在使用时应尽量关注心跳答复，如遇到 webhook 没有发送消息时，可以先查看心跳是否正常。

配置 webhook 接收器端示例

下载HTTP 服务二进制

curl -O  https://res.ones.pro/script/k3stool/webhook_client

将下载后的webhook_client复制到容器内并启动

containerID=$(docker ps |grep $(./json-util -config config.json -operator select -key deploy_name) | grep '0.0.0.0:'$(./json-util -operator select -key port -config ./config.json)'->' | awk '{print $1}')
docker cp webhook_client $containerID:/
docker exec -it $containerID bash
chmod +x /webhook_client
cd /
./webhook_client &

检查webhook_client启动是否正常

netstat -tunlp

当观察到如下输出，则启动已经完成

配置 webhook 接收器端点

1. 点击新建「监听器」，URL 填写：http://127.0.0.1:8888/webhook/accept，点击「保存并启用」

2. 更改工作项的状态

3. 查看 webhook 消息通知(在 webhook_client 目录下) webhook.log 结构如下：

# 查看日志
cd /
tail -f webhook.log

当观察到如下输出时，则webhook功能正常

配置关闭 Webhook

修改配置

登陆 ONES 服务器，进入当前运行中实例的安装目录

sudo cd /data/ones/pkg/ones-example-3.14.xxxxx

修改<enable_webhook>配置的值为 false

./json-util -config config.json -operator add -key enable_webhook -valtype bool -value false

重启容器

注意：执行以下命令将造成 ONES 服务暂时不可用

containerID=$(docker ps |grep $(./json-util -config config.json -operator select -key deploy_name) | grep '0.0.0.0:'$(./json-util -operator select -key port -config ./config.json)'->' | awk '{print $1}')
./onesconfigure update $containerID -r

当观察到如下输出，则重启已经完成。稍等几分钟后 ONES 服务将可以正常访问

[root@localhost ones-example-3.14.xxxxx]# containerID=$(docker ps |grep $(./json-util -config config.json -operator select -key deploy_name) | grep '0.0.0.0:'$(./json-util -operator select -key port -config ./config.json)'->' | awk '{print $1}')
[root@localhost ones-example-3.14.xxxxx]# ./onesconfigure update $containerID -r
[INFO] 2023/05/30 10:36:07 WARNING: key 'InternalBaseUrl' not exist in config file '/data/conf/options.json'
[INFO] 2023/05/30 10:36:07 WARNING: key 'enable_automation' not exist in config file '/data/conf/options.json'
[INFO] 2023/05/30 10:36:07 WARNING: key 'ConfluenceBackMaxSize' not exist in config file '/data/conf/options.json'
[INFO] 2023/05/30 10:36:07 WARNING: key 'EnableModifyLoginPageLogo' not exist in config file '/usr/local/ones-ai-project-api/conf/config.json'
[WARN] 2023/05/30 10:36:07 update apps
[INFO] 2023/05/30 10:36:10 restart container...
[INFO] 2023/05/30 10:36:21 restart container success, container_id=f8caed932bff

验证

登陆 ONES 系统，进入 「团队配置中心」，看不到外部通知选项则正常

---

如果上述方法都不能解决，请联系 ONES 工程师