---

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/free-pro-team@latest/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 长连接与短连接的区别