跳到内容
Localtonet Localtonet 控制台

Webhook

获取本页帮助
本页内容 9 个章节
  1. 工作原理
  2. 开始之前
  3. 创建 Webhook
  4. 打开 Webhook
  5. 选择要通知哪些事件
  6. 创建
  7. Webhook 列表
  8. Localtonet 发送的请求
  9. 投递
  10. 接收端示例
  11. 测试你的 Webhook
  12. 故障排除
  13. 相关页面

Webhook 会让 Localtonet 在设备(AuthToken)或隧道连接或断开时调用你的一个 URL。你可以用它来提醒团队、重启服务,或者让你自己的状态页保持最新。

工作原理 #

  • Webhook 属于某个 令牌组。它会按你的选择,监视该组中的 AuthToken、这些令牌的隧道,或者两者都监视。
  • 当被监视的令牌或隧道的状态变为已连接或已断开时,Localtonet 会向你的 URL 发送一个带有小型 JSON 正文的 HTTP POST 请求。
  • 你可以选择想要哪两种事件:已连接、已断开,或者两者都要。

开始之前 #

  • 一个包含你想监视的 AuthToken 的令牌组。在 我的令牌 下创建组;参见 AuthToken。
  • 一个可从互联网访问、并接受带 JSON 正文的 POST 请求的 HTTP 或 HTTPS 端点。
  • 你自己的账户控制台。在团队控制台中工作时,不会显示 Webhook 菜单项。

创建 Webhook #

  1. 打开 Webhook #

    在控制台菜单中打开 Webhook。

  2. 选择要通知哪些事件 #

    设置作用
    启用令牌 Webhook当该组的某个 AuthToken 连接或断开时发送请求,也就是该设备上的 Localtonet 客户端上线或离线时。
    启用隧道 Webhook当属于该组某个 AuthToken 的隧道连接或断开时发送请求。
    连接时发送在变为已连接时发送请求。
    断开时发送在变为已断开时发送请求。
    认证令牌组要监视的令牌组。必填。
    Webhook URLLocaltonet 调用的地址。必填。

    请在两种 Webhook 类型中至少开启一种,并在两种通知类型中至少开启一种。

  3. 创建 #

    选择 创建。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 相同。
ActionDateLocaltonet 登记到这一变化的时间。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 最小版本:

receiver.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 #

  1. 把一个测试设备的 AuthToken 放入该 Webhook 的令牌组。
  2. 在该设备上用这个令牌启动 Localtonet 客户端。如果 连接时发送 已开启,你的端点会收到 Type Token、Status Connected。
  3. 用 Ctrl + C 停止客户端。你的端点会收到 Status Disconnected。
  4. 如果 启用隧道 Webhook 已开启,请在“我的隧道”下启动和停止该令牌的一个隧道,以获得隧道事件。

还没有公共端点?请在你的电脑上运行接收端,并通过使用与你正在监视的令牌 不同 的 AuthToken 的 Localtonet HTTP 隧道 把它发布出去。隧道的请求检查器随后会显示每一次 Webhook 调用;参见 日志与检查。

故障排除 #

“请至少开启一种 Webhook 类型。”或“请至少开启一种通知类型。”

在选择 创建 之前,请先打开 启用令牌 Webhook 或 启用隧道 Webhook,以及 连接时发送 或 断开时发送。

“请选择组!”

在 认证令牌组 下选择一个令牌组。如果列表为空,请在 我的令牌 下创建一个组,并把你的令牌加入其中。

没有收到任何请求

请检查设备的 AuthToken 是否属于该 Webhook 所监视的组,列表中对应的开关是否显示 已启用,以及该 URL 是否可从互联网访问(不是 localhost 或私有地址)。你可以自己测试这个 URL:

Bash
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。

支持