Webhooks 教程：Webhooks 入门指南

介绍

学习一门新技术时，有三个重要的问题需要思考：是什么、为什么以及如何学习。在上一篇文章中，我们深入探讨了什么是 Webhook 以及为什么需要它们。Webhook 是用户定义的 HTTP 回调函数，可用于在两个独立的在线应用程序之间建立通信。当一个应用程序中发生事件时，该应用程序可以使用 Webhook 将事件通知以及事件数据发送到另一个应用程序。

Webhook 的工作原理

Webhook 通信是通过从源应用程序向目标应用程序发送 HTTP 请求来实现的。当源应用程序中发生事件时，会触发一个 HTTP 请求，该请求可能包含与您事件相关的数据。此 HTTP 请求将发送到目标应用程序的端点。这是目标应用程序提交给源应用程序的端点，用于接收 Webhook 请求。该端点通常称为 Webhook URL。

Webhook 请求可以使用 POST 或 GET 请求方法发送。这取决于 Webhook 提供商的偏好设置——如何使用请求的信息始终可以在提供商的文档中找到。下一节将详细介绍如何从提供商的文档中查找有关 Webhook 的正确信息。

如何阅读 webhook 的文档

对于大多数开发者来说，浏览技术文档并不是一件充满乐趣的事情，Webhook 提供商的文档也不例外。我曾经在不同提供商的 Webhook 文档中寻找合适的信息，也曾遇到过不少挫折。所以，我想分享一些我多年来在使用 Webhook 过程中发现的实用技巧。

• 查找开发人员部分： Webhook 是 webhook 提供商的编程接口的一部分，因此您很可能会在提供商网站的此部分中找到有关 webhook 的文档。
• 使用搜索栏：大多数文档都具有搜索功能，您可以使用正确的关键字快速找到所需的信息，例如“webhook events*”。
• 检查事件类型：事件是 Webhook 的核心关注点。了解事件类型有助于您理解可以订阅哪些事件。例如，电商网站可以允许订阅某些事件，例如商品添加到购物车、商品购买等。
• 查找有关 Webhook 安全性的信息： Webhook 请求是常规 HTTP 请求，因此容易受到 HTTP 请求面临的所有安全威胁。您需要检查提供商 Webhook 的安全性信息，例如 IP/域名白名单、身份验证令牌、API 密钥等。
• 速率限制和重试：与常规 HTTP 请求一样，Webhook 请求可能会失败，您还需要考虑接收请求的 API 端的可扩展性。因此，了解最大并发请求数以及该值是否可以配置非常重要。您还需要了解服务商是否会自动重试失败的请求，如果没有，您可能需要自行设置系统来实现。

教程：如何使用 Stripe 设置 webhook

现在我们已经掌握了丰富的 Webhook 知识，让我们通过一个使用Stripe Webhook 的练习来将这些知识付诸实践。Stripe 是一个易于设置的电子支付网关，为 Web 应用程序提供支付基础设施。第一步是注册一个 Stripe 账户并注册 Stripe Webhook，以便在一个演示Node.js服务器上接收 Webhook 请求。

从 Stripe 文档中获取关键信息

首先，我们需要扎实的 Stripe webhook 知识基础，这可以通过Stripe 文档来获取。有关 webhook 的信息可以在开发者工具 → Webhook 的文档中找到。

在这里，您可以找到有关使用不同编程语言、检查 Stripe验证签名以进行身份​​验证、Stripe webhook 集成最佳实践，甚至示例集成的信息。

创建 Stripe 账户

目前注册 Stripe 账户只需要一个电子邮件地址。请前往Stripe 注册页面创建一个新账户。注册后，您需要验证您的电子邮件地址。

克隆 Node.js API

设置好 Stripe 帐户后，下一步就是克隆 Node.js API 的演示版本。我们将要使用的 API 可以在Hookdeck 的 GitHub 仓库中找到。运行以下命令克隆此仓库：

git clone https://github.com/hookdeck/nodejs-webhook-server-example.git

这将使该项目在您运行命令的文件系统上的位置可用。

导航到项目的根目录并通过运行以下命令安装所需的依赖项：

cd nodejs-webhook-server-example
npm install

安装完成后，您可以使用以下命令运行 Node.js 服务器：

npm start

这将启动 API 应用程序并在屏幕上打印一条消息，表明 API 现在正在运行并监听端口上的连接1337。

用于 webhook 请求的端点/stripe-webhooks-endpoint可以在文件中找到，routes.js如下所示：

router.post("/stripe-webhooks-endpoint", bodyParser.raw({type: 'application/json'}), function(req, res) {
  console.log(req.body);
  res.send("Stripe Successfully received Webhook request");
});

该端点接收 webhook 请求，将请求正文打印到控制台，并返回一条消息。

获取 webhook URL

要使源应用程序发送 Webhook 请求，目标应用程序需要向源应用程序注册一个 Webhook URL。出于安全考虑，大多数 Webhook 提供商还要求此端点使用HTTPS协议。因此，我们需要一个使用 HTTPS 协议的可公开访问的 URL。

幸运的是，Hookdeck CLI正是为此而生。使用 Hookdeck CLI，您可以在本地接收 Webhook 并无缝调试。请参阅CLI 文档，了解如何在您的操作系统上安装和设置该工具。

设置过程完成后，下一步是使用 CLI 生成指向正在运行的 API 应用程序的 webhook URL。为此，请运行以下命令：

hookdeck listen 1337

此命令将启动一个交互式会话，CLI 将在此会话中收集有关您即将创建的端点的信息。以下是您需要回答的问题以及每个问题的答案。请确保Enter在回答每个问题后按下相应的键。

• 选择来源？答：选择“创建新来源”
• 你的新来源标签应该是什么？答：输入文本条纹
• Webhook 应该转发到哪个路径（例如：/webhooks）？答：输入/stripe-webhooks-endpoint
• 连接标签（例如：我的 API）是什么？答：输入“我的 Stripe API”

有了这些信息，CLI 将开始生成 URL 的过程，完成后，您将看到 URL 打印到屏幕上，并且 CLI 指示它已准备好接收请求。

复制 webhook URL，因为下一部分将需要它。

在 Stripe 上设置 webhook

现在我们已经完成了目标应用程序上的设置，是时候在 Stripe 上订阅 webhook 了。

在 Stripe 控制面板中，前往“开发者”→“Webhooks”。在“Webhooks”页面上，点击+ Add endpoint屏幕右上角的****按钮。此操作将弹出一个类似下图的对话框：

在对话框中，将从 CLI 复制的 webhook URL 添加到Endpoint URL字段中。接下来，点击Events to send下拉菜单，选择account.updated每次更新 Stripe 帐户时触发的事件。点击Add endpoint按钮完成此过程。

这将在您的 Stripe 帐户和本地计算机上运行的事件 API 应用程序之间建立连接account.updated。成功添加 webhook 后，您将看到如下所示的屏幕：

测试 webhook 请求

设置好 webhook 连接后，就可以测试一下了。Stripe 提供了一种发送测试 webhook 的方法，它可以模拟你注册的事件。这对于测试和调试非常方便。

在上方显示的 Webhook 屏幕右上角，点击Send test webhook按钮。这将弹出一个对话框，供您选择要发送测试的事件。请参阅下面的对话框：

确保选中该account.updated事件并点击Send test webhook按钮。这将触发一个指向你的 webhook URL 的 webhook 请求，该请求将发送到你在创建 URL 时指定的端点（即/stripe-webhooks-endpoint）。

观察运行该hookdeck listen 1337命令的终端窗口。您将看到 webhook 请求打印到终端，如下所示：

打印信息中的最后一项是一个端点，用于查看刚刚收到的 webhook 请求的详细信息。复制此 URL 并将其加载到浏览器中，您将看到如下所示的事件详细信息屏幕。

此屏幕包含有关 webhook 请求的详细信息以及有效负载中发送的请求主体（如果有）。

这将使您能够检查请求数据并编写代码来响应它。

使用 webhook 时的重要注意事项

Webhook 是一种简单的通信设置，因此，人们可能会倾向于简化该过程。然而，在使用 Webhook 时，有一些非常重要的事项需要考虑，其中一些将在下文中解释。

• 可扩展性：您订阅的事件越多，收到的请求就越多，而且有些事件是高频事件。使用 Webhook 时，流量突然激增的情况并不少见。如果您的端点不堪重负，这种来自高频事件的 Webhook 请求突然激增最终可能导致服务器瘫痪。解决这个问题的方法之一是使用消息队列进行异步处理，或者使用像Hookdeck这样的在线服务。
• 请求失败：大多数 Webhook 请求都遵循“发射后不管”的流程，即请求发送时无需源端确认其是否成功到达目标端。因此，如果您的终端节点发生错误，并且未重试 Webhook 请求，则数据可能会丢失。这可能会对系统的完整性造成严重损害。您需要确保失败的请求能够重试，并且请求数据在重试之间能够持久保存。某些提供商会在收到目标应用的错误状态代码时自动执行此操作。如果提供商不提供此功能，则您需要自行设置。
• 安全性：如前所述，webhook 请求是常规的 HTTP 请求，因此您需要注意对发送到服务器的请求进行身份验证。某些提供商（例如 Stripe）在标头中嵌入了 API 密钥和安全签名，以便您验证请求。

结论

Webhook 为在线应用程序提供了无缝的实时通信系统。应用程序可以相互通知和共享正在发生的事件信息，并形成一系列自动化工作流，为自身及其用户带来更多价值。本文以 Stripe Webhook 为例，演示了如何使用 Webhook。大多数 Webhook 提供商的流程非常相似，仅在请求的形式上存在差异。因此，您可以将本文中学到的知识运用到与其他 Webhook 提供商的合作中。祝您编码愉快！