Webhooks、webhook URL 和 webhook 的示例实现

引言

本文讨论了webhooks、webhook Url，最后展示了一个使用 webhooks 的示例。我最近不得不实现 webhook url 的概念，因为这是我第一次听说 webhooks，所以我费了很大的劲才理解“webhook”到底是什么意思，以及如何创建一个。但当我真正理解了整个概念后，我明白 webhook 不过是一个简单的 HTTP POST！

在探索 webhooks 的过程中，我查阅了很多文章，希望能找到一篇能在一个地方清晰地解释整个概念的文章，但我没能找到。所以我决定用自己的话写一篇。我想说，下面的文章纯粹是我自己的理解。如果我哪里错了，请务必纠正我，因为我不想传播错误的信息。欢迎提出意见和建议……

什么是 web hook？

从技术角度讲，webhook 基本上是用户定义的 HTTP 回调，当源站点发生特定事件时触发。当事件发生时，源站点会向指定为 webhook 的 URL 发送 HTTP 请求。

webhook 的一些应用包括

1. Notifications
2. 数据同步
3. 修改
4. 插件

以上几行摘自维基百科。下面给出一个简单的解释。

简单来说，webhook 不过是一个接受 HTTP POST 请求的 web 服务（或者说，监听请求）来自源。所以，webhook 又是一个REST 服务，它接受数据或数据流。

举个例子，我们考虑一个网站 http://www.fullcontact.com。FullContact 存储了注册用户的所有社交资料详情。要访问特定用户的所有社交资料数据，我们需要使用电子邮件 ID 和 API 密钥（该密钥由 FullContact 在用户注册网站后生成并提供）查询 FullContact 数据库。

我使用我的电子邮件 ID 查询了 FullContact 数据库，获取我的社交资料详情，这是我从网站收到的响应。响应采用 JSON 格式。

 

现在假设我有一个需求，我有一个电子邮件 ID 列表，我需要保存每个电子邮件 ID 收到的 JSON。有两种方法可以实现这一点。

一种是手动获取每个电子邮件 ID，创建查询 URL，访问 FullContact 数据库并保存收到的 JSON。如果电子邮件 ID 数量有限，这很容易做到。但是如果电子邮件 ID 数量达到数万甚至数百万，那么这绝对不是任何人会喜欢的方式。

另一种方法是创建一个小型应用程序，遍历电子邮件 ID 列表，为每个电子邮件 ID 创建查询 URL，并访问 FullContact 数据库以获取与该特定电子邮件 ID 相关的 JSON。但在这里，我们没有使用任何浏览器。那么 JSON 如何保存呢？这就是 web hook 派上用场的地方。

对于上述要求，如前所述，一个示例应用程序将只遍历电子邮件列表并查询 FullContact。然后应该创建第二个 REST 服务，该服务接受 JSON 作为输入并将其保存到文件或其他位置。在这种情况下，这个 REST 服务就是我们的 web hook，它会持续监听 FullContact 网站，以防有任何查询发送给它。

要查询 FullContact 数据库，必须创建一个查询 URL，其形式为：

https://api.fullcontact.com/v2/person.json?email=XXXXX@YYYY.ZZZZ&apiKey=XXXXXXXXXXXXXXXX 

上述查询，当在网页浏览器中打开时，将显示与指定电子邮件 ID 相关的 JSON，如上面的屏幕截图所示。

要使用 web hook 获取多个电子邮件的 JSON（上述第二种方法），只需在 URL 中的“email”参数之后，将以下内容附加到上述查询 URL 中即可。

&webhookUrl=http://yourRestServiceAddress.svc

所以带有 web hook 的查询 URL 将看起来像这样

https://api.fullcontact.com/v2/person.json?email=XXXX@YYYY.ZZZ&webhookUrl=http://myServer/MyServiceUrl&apiKey=XXXXXXXXXXXXXXXXXXXX 

当我们使用这个 URL 访问 FullContact 网站时，它将导致网站将与电子邮件 ID 相关的 JSON 发送到指定的“webhook URL”，即我们的 REST 服务。这里最重要的一点是，为了让我们的 REST 服务作为 web hook 工作，它必须暴露在互联网上。如果它只是内部托管在服务器中，web hook 将无法工作。它必须托管在暴露于互联网的位置。

我们还可以指定一个 webhook ID 以在服务端使用。webhook ID 的指定方式与 webhook URL 相同。Full Contact 会原样将其发送到服务。这个 webhook ID 可以在我们的服务端用于识别 JSON 属于谁。只需在指定 API 密钥之前，在上述 URL 中添加“&webhookId=XYZ”。

如果在浏览器中打开，当 webhook URL 查询打开时，将显示以下响应。

 

如果您想查看发送到 web hook 的 JSON，您可以在 postcatcher.in 网站中创建一个虚拟 web hook。

下面的屏幕截图显示了当向 FullContact 发送特定电子邮件 ID 的查询时，虚拟 web hook 收到的 JSON。屏幕截图不是很清晰，但它只显示了该电子邮件 ID 的 JSON。

 

在我们的服务侧，也就是 webhook 侧，我们只需将收到的 JSON 流反序列化为相应的类，并根据需要进行处理即可。

其他有助于更好理解本文的有用链接

• (JSON 反序列化教程链接。主要讨论使用 Newtonsoft.json.dll)
• (Newtonsoft.JSON 文档链接)

Full Contact 发送的上述 JSON 包含两部分，“result”和“webhookId”。result 标签包含与电子邮件 ID 对应的 JSON（即，与联系人对应的 JSON）。另一部分 webhookId 包含我们在 URL 中传递的 ID。它会原样返回。

创建 REST 服务的教程

有关如何创建 REST 服务的教程，请参阅此链接。希望这对您有所帮助。欢迎评论或提交对上述文章的任何更正。