当前位置：首页 > news >正文

使用 ngrok 在本地测试 Paddle Webhook 教程

news 2025/10/30 9:55:06

在本地测试 Paddle Webhook 时，ngrok 是一个必不可少的“神器”。

Paddle 的服务器需要一个公开的、能在互联网上访问到的网址来发送 Webhook 事件。但你的本地开发环境（比如 localhost:3000）是在你的私人网络里的，Paddle 无法直接访问它。

ngrok 的作用就是创建一个安全的“隧道”，将一个公开的 ngrok.io 网址，直接指向你本地的 localhost:3000。

我将为你提供一份详尽的、一步到位的教程。

使用 ngrok 在本地测试 Paddle Webhook 教程

这个教程分为三步：

安装和配置 ngrok。
启动 ngrok 隧道。
在 Paddle Sandbox 环境中配置 Webhook 端点。

第一步：安装和配置 ngrok (只需一次)

注册 ngrok 账号:
- 访问 ngrok Dashboard。
- 使用你的 GitHub、Google 账号或邮箱免费注册一个账号。这一步很重要，因为注册后你会得到一个认证令牌 (Auth Token)，可以让你使用更长的会话时间和更多功能。
安装 ngrok:
- ngrok 是一个单一的可执行文件，安装非常简单。
- 对于 Ubuntu (你的VPS) 或 macOS (使用 Homebrew):
  codeBash
```
brew install ngrok/ngrok/ngrok
```
- 对于 Windows (使用 Chocolatey):
  codeBash
```
choco install ngrok
```
- 或者，直接下载: 去 ngrok 下载页面下载对应你操作系统的压缩包，然后解压。
连接你的账号 (配置 Auth Token):
- 登录你的 ngrok Dashboard。
- 在左侧菜单，点击 “Your Authtoken”。
- 你会看到一条命令，格式是 ngrok config add-authtoken <YOUR_AUTH_TOKEN>。
- 复制这条完整的命令，并在你的终端里运行它。
  codeBash
```
ngrok config add-authtoken 2XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
- 这条命令会将你的认证令牌保存到 ngrok 的配置文件中，你只需要做这一次。

第二步：启动 ngrok 隧道

现在，假设你的 Next.js 应用正在本地运行，监听 3000 端口。

启动你的本地开发服务器:
- 在你的项目目录中，确保 pnpm dev 正在运行。
  codeBash
```
pnpm dev
# ✓ Ready in 2.7s
# - Local: http://localhost:3000
```
打开一个新的终端窗口:
- 不要在运行 pnpm dev 的同一个终端里操作。
启动 ngrok:
- 在新的终端窗口中，运行以下命令：
  codeBash
```
ngrok http 3000
```
- 这条命令的意思是：“请为我本地的 http://localhost:3000 服务创建一个公开的HTTP隧道。”

获取你的公开网址:

ngrok 启动后，你会看到一个类似这样的界面：

codeCode

ngrok                                                              (Ctrl+C to quit)Session Status                online
Account                       Your Name (Plan: Free)
Version                       3.x.x
Region                        United States (us-cal-1)
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://<RANDOM_SUBDOMAIN>.ngrok-free.app -> http://localhost:3000Connections                   ttl     opn     rt1     rt5     p50     p900       0       0.00    0.00    0.00    0.00

关键信息: 找到 Forwarding 那一行。https://<RANDOM_SUBDOMAIN>.ngrok-free.app 就是 Paddle 需要的公开网址。
请复制这个 https 开头的网址。例如：https://abcd-1234-5678.ngrok-free.app。

第三步：在 Paddle Sandbox 中配置 Webhook

现在你有了公开的网址，我们去 Paddle 设置它。

登录你的 Paddle Sandbox 账号:
- 访问 Paddle Sandbox。
进入 Webhook 设置:
- 在左侧菜单，找到 Developer Tools -> Events -> Webhook alerts。
添加一个新的 Webhook 端点:
- 在 "URL for alerts" 输入框中，粘贴你刚刚从 ngrok 复制的网址，并在后面加上你的 Webhook API 路由路径。
  - 例如：https://abcd-1234-5678.ngrok-free.app/api/paddle/webhook
- 注意: 这里的 /api/paddle/webhook 应该与你项目中处理 Paddle Webhook 的 API 路由文件路径 (src/app/api/paddle/webhook/route.ts) 相匹配。
获取 Webhook 签名密钥:
- 在同一个页面下方，你会看到 “Signature verification” 部分。
- 点击 “View signing secret”，然后复制那串密钥。
配置你的本地环境变量:
- 打开你本地的 .env.local 文件。
- 将刚刚复制的密钥，粘贴到 PADDLE_SANDBOX_WEBHOOK_SECRET 变量中。
  codeEnv
```
# .env.local
PADDLE_SANDBOX_WEBHOOK_SECRET="pdl_whs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```
- 重启你的 pnpm dev 服务器，以确保它加载了这个新的环境变量。

大功告成 & 如何调试

现在，你的设置已经全部完成！

当你在你的应用中触发一个会产生 Webhook 的事件时（比如完成一次模拟购买），Paddle 会将事件发送到你的 ngrok 公开网址。
ngrok 会将这个请求安全地转发到你本地的 http://localhost:3000/api/paddle/webhook。
你的 Next.js API 路由会接收到这个请求，并使用 PADDLE_SANDBOX_WEBHOOK_SECRET 来验证签名的合法性，然后处理事件。

调试小贴士:

ngrok 的终端窗口会实时显示所有通过隧道的HTTP请求。你可以看到请求的URL、方法、状态码等，非常适合用来确认请求是否已经到达。
你也可以访问 ngrok 界面上显示的 Web Interface 地址（通常是 http://127.0.0.1:4040），它提供了一个更详细的请求检查器，你可以看到完整的请求头和请求体。

查看全文

http://www.dtcms.com/a/545399.html