GitLab webhook简要说明及使用方式

Webhook是什么

webhook为什么叫webhook呢，是Jeff Lindsay在2007提出来的。

webhook是一个web自定义回调函数，当程序发生警报行为时，会自动回调调用指定的url。webhook的回调url可以是第三方应用，可以是webhook内应用。

传统的Rest Api，一般用get、post的方式提交数据给服务器，也用来获取服务器的数据。而这些Rest Api是客户端主动向服务器拿取数据的，只是‘单方面’的操作。

后来自然而然出现了轮询、websocket等技术，让服务器‘主动’通知客户端做出改变。上面这些技术可以实现我们的端到端之间的通讯。但是做得还不够好。那么，webhook就出现了，webhook就是web服务使用Http Post请求为其它服务提供实时信息的一种方式。

一个 webhook 会在它调用时就传递数据到其它的应用，这表明你可以立即得到数据。这让使用了 webhook 的生产者和消费者都变的更有效率。

GitLab Webhook的事件

• Push events
• Tag push events
• Comments
• Issues events
• Confidential Issues events
• Merge Request events
• Job events
• Pipeline events
• Wiki Page events

GitLab Webhook示例（以push事件为例）

image.png

1. 打开项目的 setting
2. 选择Integration
3. 在URL中填写接收请求的接口地址(GitLab发送webhook post请求的content-type为application/json)
4. 从Trigger中选择需要监听的事件。（下面以push events为示例）

注：gitlab 10.6 版本以后为了安全，不允许向本地网络发送webhook请求，如果想向本地网络发送webhook请求，则需要使用管理员帐号登录进入Admin area，在Admin area中，在settings标签下面，找到OutBound Request，勾选上Allow requests to the local network from hooks and services ，保存更改即可向本地网络发送webhook请求。
不能修改的话，则需要将接收webhook请求的是服务部署到可以通过公网IP或域名的机器上。

GitLab Webhook push event request报文结构

下面是某一次push的是Webhook报文，关键信息见注释。

Request headers:
Content-Type: application/json
X-Gitlab-Event: Push Hook
Request body:
{
  "object_kind": "push",
  "event_name": "push",
  "before": "0637d8d49c339303138bfc0ce3b552dc1d00346e", //本次push前的git 版本号
  "after": "3b2f25ab6b642e7eee0904f26fea9a210a3dd9ca",//本次push生成的git 版本号
  "ref": "refs/heads/wh",
  "checkout_sha": "3b2f25ab6b642e7eee0904f26fea9a210a3dd9ca",//本次push生成的git 版本号SHA
  "message": null,
  "user_id": 401,
  "user_name": "符标杉",
  "user_username": "fubs001",
  "user_email": "fubs001@cmft.com",
  "user_avatar": "http://www.gravatar.com/avatar/13324b97ba95e86d66e846a15b1e350a?s=80&d=identicon",
  "project_id": 2615,
  "project": {
    "id": 2615,
    "name": "iocp-msg-api",
    "description": "消息引擎1.2后台api",
    "web_url": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api",
    "avatar_url": null,
    "git_ssh_url": "git@git.dev.cmrh.com:cmft-iocp/coco/iocp-msg-api.git",//项目ssh地址
    "git_http_url": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api.git",//项目http地址
    "namespace": "coco",
    "visibility_level": 0,
    "path_with_namespace": "cmft-iocp/coco/iocp-msg-api",
    "default_branch": "master",
    "ci_config_path": null,
    "homepage": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api",
    "url": "git@git.dev.cmrh.com:cmft-iocp/coco/iocp-msg-api.git",
    "ssh_url": "git@git.dev.cmrh.com:cmft-iocp/coco/iocp-msg-api.git",
    "http_url": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api.git"
  },
  "commits": [//本次push的commits信息
    {
      "id": "3b2f25ab6b642e7eee0904f26fea9a210a3dd9ca", //commit id
      "message": "test webhook\n", //commit message
      "timestamp": "2018-12-29T16:45:02+08:00", //commit time
      "url": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api/commit/3b2f25ab6b642e7eee0904f26fea9a210a3dd9ca",
      "author": {
        "name": "fubs",//committer
        "email": "fubs001@cmrh.com"
      },
      "added": [

      ],
      "modified": [
        "src/main/java/com/cmft/im/message/Login/restController/LoginInController.java"
      ],
      "removed": [

      ]
    }
  ],
  "total_commits_count": 1,
  "repository": {
    "name": "iocp-msg-api",
    "url": "git@git.dev.cmrh.com:cmft-iocp/coco/iocp-msg-api.git",
    "description": "消息引擎1.2后台api",
    "homepage": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api",
    "git_http_url": "http://git.dev.cmrh.com/cmft-iocp/coco/iocp-msg-api.git",
    "git_ssh_url": "git@git.dev.cmrh.com:cmft-iocp/coco/iocp-msg-api.git",
    "visibility_level": 0
  }
}