Webhook

介绍平台事件回调机制。

平台的通知服务(notify)提供了回调webhook机制，允许外部系统实时接收平台的事件以及事件相关的资源信息。

如何启用Webhook通知

1. 创建webhook机器人

在认证与安全->消息中心->机器人管理页面中点击新建按钮,选择类型为Webhook的机器⼈。

2. 配置Webhook

关于header,body,msg_key字段的说明：

  header: 特指额外附加的webhook请求头，可为空。
  body: 特指额外附加的webhook报文，可为空。
  msg_key: 特指对于所需文案的key，可为空，为空时默认key为Msg

  注: 当body与msg_key同名时，body优先，会导致文案主体信息丢失，故msg_key与body不得同名。

例：

webhook配置:

配置完成后点击确定，后确认webhook机器人状态为启用。

3. 启用消息订阅并指定接受人

在认证与安全->消息中心->消息订阅设置页面中，在你感兴趣消息的接收管理中新建机器⼈类型的接收⼈，并选择上述新创建的Webhook机器⼈。

⽬前⽐较统⼀的是配置 “资源创建、删除发送通知”,“资源调整配置发送通知”,“资源属性变更(含密码变更)发送通知”以及“资源同步发送通知”（也可能叫做“resource sync”）。

资源属性变更(含密码变更)发送通知: 指在修改资源基础属性时会发送通知，如：修改资源名称，修改资源备注等。
资源操作失败发送通知: 代表的是资源在执行操作时失败会发送通知，如：资源新建失败，资源调整配置失败等。
...

配置完成后点击确定，后确认消息订阅状态为启用。

4. 最终Webhook效果

webhook接收到消息如下：

response header:
Host: xxx
User-Agent: yunioncloud-go/201708
Accept: */*
Accept-Encoding: *
Content-Type: application/json
Test: test // 此处为附加请求头
X-Request-Id: 60ec3e
X-Yunion-Event: HOST/UPDATE
X-Yunion-Parent-Id: 0
X-Yunion-Peer-Service-Name: notify
X-Yunion-Span-Id: 0.0
X-Yunion-Span-Name:
X-Yunion-Strace-Debug: true
X-Yunion-Strace-Id: e7b586c9

response body:
{
    "body_test":"test", // 此处为附加报文
    "test":"{\"action\":\"update\",\"resource_details\":{\"access_ip\":\"\",\"access_mac\":\"\",\"name\":"yunion",...\"}, \"resource_type\":\"host\",\"result\":\"succeed\"}", // 当msg_key为空时key默认为Msg
    "action":"update",
    "resource_details":{ // 此处为资源详细信息
        "access_ip":"",
        "access_mac":"",
        "is_baremetal":false,
        "is_emulated":false,
        "is_import":false,
        "is_maintenance":false,
        "is_prepaid_recycle":false,
        "is_public":true,
        "isolated_device_count":0,
        "manager_uri":"",
        "mem_cmtbound":1,
        "mem_commit":0,
        "mem_commit_bound":1,
        "mem_commit_rate":0,
        "mem_reserved":1328,
        "mem_size":11957,
        "metadata":{},
        "name":"yunion",
        ...
    },
    "resource_type":"host",
    "result":"succeed"
}

支持Webhook事件通知的资源

云管平台⽀持创建、删除、更新、删除的资源：宿主机，虚拟机、硬盘、RDS、Redis、LB、EIP、VPC、IP⼦⽹、安全组、证书、DNS、NAT、对象存储OSS、NAS；
云管平台支持更新的资源：虚拟机，用户，宿主机
云管平台只⽀持同步的资源：Webapp、Azure LB；
云管平台⽀持同步加删除的资源：CDN、WAF、Kafka、Elasticsearch、MongDB、TDSQL(RDS)、 Memcached(RDS )

Webhook消息格式

Webhook回调请求都携带http header 'X-Yunion-Event'，代表触发Webhook回调通知的事件类型。

除"验证事件"外，reponse body示例如下：

{
  "action": "<action>",
  "resource_type": "<resource_type>",
  "resource_details": {...}
}

都包含如下三个字段：资源同步发送通知: 代表的是云账号同步触发的本地资源数据与云上资源数据的同步。

action: 表示动作（create/update/delete 等等）
resource_type: 表示资源类型，⽐如 server, user等
resource_details: 表示资源的详情信息，其的内容与通过API获取的资源详细信息一致

资源同步事件

有三种特殊的action事件：sync_create/sync_update/sync_delete 代表的是云账号同步触发的本地资源数据与云上资源数据的同步。

sync_create 同步了⼀个新的云上资源
sync_update 本地资源根据云上资源更新
sync_delete 本地资源对应的云上资源已经被删除

验证事件

添加webhook时，平台会向webhook发起VALIDATE类型的调用，webhook需要处理这类请求，返回200的成功响应。

Method: POST
Header:
 Content-Type: application/json
 X-Yunion-Event: VALIDATE
 User-Agent: yunioncloud-go/201708
 Content-Length: 37
 Accept: */*
 Accept-Encoding: *
Body:
{
 "Msg": "This is a validate message."
}

模板启用

目前还可通过climc命令调整webhook是否启用模板: climc notify-robot-update <robot-id> --use-template true

启用模板后，发出的报文将与常规机器人通知一致，将不再返回json数据，而是返回文案信息。

消息没有正常发送的可能原因

1、确认消息订阅、接受人、机器人是否启用，若为接受人，确保通知渠道是否正常。

2、确认资源是否在消息订阅的范围内。

3、确认是否模板异常导致通知失败

查看操作日志：climc action-show --type notification --fail

若出现template关键字，可通过删除notify.topic_tbl,notify.subscriber_tbl表后重启notify服务，重新覆盖模板文案（注：会导致丢失所有消息订阅关联关系）。
或修改notify.topic_tbl中的title_cn,title_en,content_cn,content_en字段，相关语法可参考go-template。

如何启用Webhook通知​

1. 创建webhook机器人​

2. 配置Webhook​

3. 启用消息订阅并指定接受人​

4. 最终Webhook效果​

支持Webhook事件通知的资源​

Webhook消息格式​

资源同步事件​

验证事件​

模板启用​

消息没有正常发送的可能原因​