Webhook
本页内容 9 个章节
Webhook 会让 Localtonet 在设备(AuthToken)或隧道连接或断开时调用你的一个 URL。你可以用它来提醒团队、重启服务,或者让你自己的状态页保持最新。
工作原理 #
- Webhook 属于某个 令牌组。它会按你的选择,监视该组中的 AuthToken、这些令牌的隧道,或者两者都监视。
- 当被监视的令牌或隧道的状态变为已连接或已断开时,Localtonet 会向你的 URL 发送一个带有小型 JSON 正文的 HTTP
POST请求。 - 你可以选择想要哪两种事件:已连接、已断开,或者两者都要。
开始之前 #
- 一个包含你想监视的 AuthToken 的令牌组。在 我的令牌 下创建组;参见 AuthToken。
- 一个可从互联网访问、并接受带 JSON 正文的
POST请求的 HTTP 或 HTTPS 端点。 - 你自己的账户控制台。在团队控制台中工作时,不会显示 Webhook 菜单项。
创建 Webhook #
-
打开 Webhook #
在控制台菜单中打开 Webhook。
-
选择要通知哪些事件 #
设置 作用 启用令牌 Webhook 当该组的某个 AuthToken 连接或断开时发送请求,也就是该设备上的 Localtonet 客户端上线或离线时。 启用隧道 Webhook 当属于该组某个 AuthToken 的隧道连接或断开时发送请求。 连接时发送 在变为已连接时发送请求。 断开时发送 在变为已断开时发送请求。 认证令牌组 要监视的令牌组。必填。 Webhook URL Localtonet 调用的地址。必填。 请在两种 Webhook 类型中至少开启一种,并在两种通知类型中至少开启一种。
-
创建 #
选择 创建。Webhook 会出现在表单下方的列表中。
Webhook 列表 #
每一行都会显示 令牌 Webhook、隧道 Webhook、组名称、URL、连接通知 和 断开通知,每个开关显示为 已启用 或 已停用。操作 列中的删除按钮会在你确认后移除该 Webhook。
Webhook 无法编辑。要更改它的 URL、组或开关,请删除它并创建一个新的。你可以为同一个组创建多个 Webhook,例如一个 URL 用于连接,另一个用于断开。
Localtonet 发送的请求 #
| 部分 | 值 |
|---|---|
| 方法 | POST |
| 内容类型 | application/json; charset=utf-8 |
| 正文 | 包含下面四个字段的 JSON 对象。 |
| 字段 | 含义 | 取值 |
|---|---|---|
Id | 标识事件所针对的令牌或隧道。 | 当 Type 为 Token 时:标识该 AuthToken。当 Type 为 Tunnel 时:隧道的数字 ID,以字符串形式发送。它与 API 中用作 tunnelId 的 ID 相同。 |
ActionDate | Localtonet 登记到这一变化的时间。 | ISO 8601 格式的日期和时间 |
Type | 对象的类型。 | Token 或 Tunnel |
Status | 新的状态。 | Connected 或 Disconnected |
令牌事件:
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}隧道事件:
{
"Id": "<TUNNEL_ID>",
"ActionDate": "2026-01-15T10:31:12.7654321+03:00",
"Type": "Tunnel",
"Status": "Connected"
}投递 #
- 失败的调用不会重试,因此你的端点应保持可用并快速响应。
- 请求不带签名或密钥请求头。要确认某次调用来自你的 Webhook,请在 URL 中放入一个较长的随机值,例如作为路径段或查询参数,并在你的接收端检查它。
- 当 Localtonet 登记到客户端已消失时才会报告断开,这可能比设备失去连接的时刻稍晚一些。
- 请用标准的 ISO 8601 解析器解析
ActionDate,并使用它携带的偏移量;不要假定固定的时区。
接收端示例 #
任何 Web 框架都可以。接收端只需要读取 JSON 正文,并以成功状态回应。下面是一个不带依赖的 Node.js 最小版本:
const http = require('http');
http.createServer((req, res) => {
let body = '';
req.on('data', chunk => body += chunk);
req.on('end', () => {
if (req.method === 'POST' && req.url === '/localtonet/<YOUR_SECRET>') {
const event = JSON.parse(body);
console.log(event.Type, event.Status, event.ActionDate);
}
res.writeHead(200);
res.end();
});
}).listen(8080);使用这个接收端时,Webhook URL 是 https://<YOUR_HOST>/localtonet/<YOUR_SECRET>。
测试你的 Webhook #
- 把一个测试设备的 AuthToken 放入该 Webhook 的令牌组。
- 在该设备上用这个令牌启动 Localtonet 客户端。如果 连接时发送 已开启,你的端点会收到
TypeToken、StatusConnected。 - 用 Ctrl + C 停止客户端。你的端点会收到
StatusDisconnected。 - 如果 启用隧道 Webhook 已开启,请在“我的隧道”下启动和停止该令牌的一个隧道,以获得隧道事件。
还没有公共端点?请在你的电脑上运行接收端,并通过使用与你正在监视的令牌 不同 的 AuthToken 的 Localtonet HTTP 隧道 把它发布出去。隧道的请求检查器随后会显示每一次 Webhook 调用;参见 日志与检查。
故障排除 #
“请至少开启一种 Webhook 类型。”或“请至少开启一种通知类型。”
在选择 创建 之前,请先打开 启用令牌 Webhook 或 启用隧道 Webhook,以及 连接时发送 或 断开时发送。
“请选择组!”
在 认证令牌组 下选择一个令牌组。如果列表为空,请在 我的令牌 下创建一个组,并把你的令牌加入其中。
没有收到任何请求
请检查设备的 AuthToken 是否属于该 Webhook 所监视的组,列表中对应的开关是否显示 已启用,以及该 URL 是否可从互联网访问(不是 localhost 或私有地址)。你可以自己测试这个 URL:
curl -X POST "<YOUR_WEBHOOK_URL>" \
-H "Content-Type: application/json" \
-d '{"Id":"test","ActionDate":"2026-01-15T10:30:00+00:00","Type":"Token","Status":"Connected"}'我收到了令牌事件,但没有隧道事件
该 Webhook 的 隧道 Webhook 必须是 已启用,并且隧道必须属于该组中的某个 AuthToken。