Luna Tech

Tutorials For Dummies.

WebHook(网络钩子)

2020-12-28


1. Webhook 和 API 的关系

A webhook, also known as a web callback, is a method that enables an app or web service to send real-time information to another application.

API:Client 找 Server 要信息。

Webhook:Reverse API, Server 主动发信息给 Client。

Webhook 的好处:Client 不用一直找 Server 要 data,减少无效沟通次数。

假如 Client 需要非常频繁地收到 Server 的信息,就要保持 connection 一直畅通(用 TCP 长连接,本文略过)。

Webhook 如何实现?

既然 Webhook 适用于 Server 向 Client 推送信息这个场景,那我们要怎么建立它们之间的沟通渠道呢?

首先呢,Client 接收信息的地址要准备好;

其次,Server 配置好接收信息的 URL,发送数据的格式(基本上都是 json),以及能够触发沟通的事件(比如:git push)。

配置好了以后,每当特定的事件发生时,Server 就会发送一个 POST 请求到这个 URL,这个请求中包含着事件相关的信息(Payload)。

PS: Payload 的数据大小并不是重点,关键要详细,因为我们是发送一个 POST 请求给 Client,Client 需要根据 payload 里面的信息来进行相关操作。

收到信息了,然后呢?

Server 发送了信息之后,收到信息的 Client 应该干什么呢?

一种比较常见的方式是:

  1. 首先,把数据存起来;
  2. 然后,告诉 server,我收到数据啦~
  3. 接下来再处理收到的数据;

2. Webhook Security

既然 Webhook 是 Server 主动给 Client 发信息,假如我们的 Client 被恶意 Server 骚扰了怎么办??

为了保证发信息的 Server 是一个正直友好的服务器,我们可以在配置 Webhook 的时候加入 Secret 来做保护。

这个保护措施是可选的,但是强烈建议大家使用!!

PS:也有一些 Client 不支持 secret,请根据自己的应用场景来查看文档和示例哦~

举例:GitHub Webhook

Reference: https://docs.github.com/en/[email protected]/developers/webhooks-and-events/securing-your-webhooks

在这个例子里面,GitHub 是 Server,你接收信息的 App 是 Client。

配置过程

  1. 生成一个 secret
    • 通过 Ruby 生成:ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'
    • 在线生成:https://www.browserling.com/tools/random-string
  2. 把这个 secret 作为 GitHub Webhook secret
  3. 在你的 Client App 里面设置一个环境变量,secret=xxxxx

实际运行过程

  1. GitHub 会用这个 secret 来生成 hash signature,在每个 POST request header 里面都能看到(X-Hub-Signature-256);
  2. Client App 接收到信息之后,用存在环境变量里面的 secret 验证这个 signature 是否合法;

3. 资料区

Webhook 讲解视频

  1. https://www.youtube.com/watch?v=J7uENSm-w1g
  2. https://www.youtube.com/watch?v=rUaDIH5ZXB8

有用的工具

  1. Webhook tester:https://webhook.site/ 假如你没有一个可供测试的地址,可以用这个网站生成的地址来配置 Server。

延伸阅读

  1. Request body encoding: JSON? x-www-form-urlencoded?
  2. TCP 长连接与短连接的区别