Webhook
发生事情时,面板会主动向您的地址发送带 JSON 的 POST 请求。每个面板最多 20 个 Webhook,每个有自己的事件。
在控制台添加 Webhook
在面板服务器上运行:veli webhook add <地址> --events a,b,c(或 --events all 表示所有事件;最多 20 个 Webhook)。地址只能是 https://,不超过 500 个字符:域名上的接收端照原样填写;IP 上使用自签证书的接收端,在末尾加上证书指纹:#sha256=<指纹>。
密钥
控制台只打印一次 Webhook 的编号和密钥——您的接收端用它校验签名。丢了?删除这个 Webhook 再重新添加:新的会有另一个密钥。
查看与删除
veli webhook list 显示 Webhook,veli webhook remove <序号或地址> 删除其中一个:之后不再向它发送事件。
veli webhook add https://example.com/veli-hook --events client.added,client.expiring,client.expiredveli webhook list
veli webhook remove 1POST /veli/events HTTP/1.1
content-type: application/json
user-agent: veli-panel/1.12.0
veli-event: client.added
veli-delivery: evt_mV3xQ8rT2kLp
veli-signature: t=1793750460,v1=5cfac9a0…
{"id": "evt_mV3xQ8rT2kLp", "event": "client.added", "at": 1793750460, "v": 1, "panel": "https://panel.example.com", "data": {"client": {…}}}openssl x509 -in cert.pem -outform DER | sha256sum
# https://203.0.113.24:8443/veli/events#sha256=<this SHA-256>- 5 秒内返回 2xx — 这样投递就完成了。耗时的工作请在响应之后再做。
- 否则——重试,持续近三天 — 其他状态码、无响应、无法连接、证书不符——分别在 10 秒、1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时、一天和又一天后重试。第十次尝试之后放弃该事件。
- 可能重复,也可能乱序 — 如果响应在途中丢失,事件可能到达两次;如果它在等待重试,可能晚于后一个事件到达:按 id 识别重复,按 at 判断顺序。
事件
客户和设备的事件在几秒内发出;与时间有关的事件——期限即将到期和已到期、流量、新周期、节点无响应或恢复——在 15 秒内发出。另外还有三个:backup.late——面板的备份超过一天没有发出去,以及 node.unreachable 和 node.reachable——节点在检测所在国家无法访问,以及重新可以访问;这三个都包含在 --events all 里。点击某个事件,即可看到请求体。
client.added添加了客户——通过 API、MCP 或服务器上的命令
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.added",
"at": 1793750400,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
}
}
}client.extended期限被修改:续期、缩短、按日期设定、推迟到首次连接。days——变化的天数(小于零——缩短,null——以其他方式设定),before——原来的结束时间
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.extended",
"at": 1793750460,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1798934400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
},
"days": 30,
"before": 1796342400,
"wait_before": 0
}
}client.expiring距到期还剩 days 天:默认在 3 天和 1 天前发出
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.expiring",
"at": 1796083200,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "soon",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 3, "bytes": null },
"…": "…"
},
"days": 3
}
}client.expired期限到期
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.expired",
"at": 1796342400,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "off",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 0, "bytes": null },
"…": "…"
}
}
}client.limit_near本周期流量已用 80 % 或 95 %——每个阈值每周期一次;percent——哪一个
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.limit_near",
"at": 1793751000,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…",
"limit": 107374182400,
"used": 85899345920
},
"percent": 80
}
}client.limited本周期流量用完
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.limited",
"at": 1793751300,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "limit",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…",
"limit": 107374182400,
"used": 107374182400
}
}
}client.reset新的流量周期开始
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.reset",
"at": 1793836800,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…",
"used": 0,
"reset": "month"
}
}
}client.first_use应用首次请求订阅:等待中的客户从此开始计期
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.first_use",
"at": 1793750520,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "gift-7731",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…",
"first": 1793750520,
"wait": 0
}
}
}client.changed设备数、速度、限额、计数、分组、外部 ID、标签、字段、备注或联系方式有变;fields——具体是哪些
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.changed",
"at": 1793750700,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month", "vip"],
"group": "",
"devices": 5,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
},
"fields": ["devices", "tags"]
}
}client.relinked更换了链接——通过 GET clients/<name> 获取
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.relinked",
"at": 1793750800,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
}
}
}client.disabled客户被停用
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.disabled",
"at": 1793750900,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "paused",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
}
}
}client.enabled客户被启用
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.enabled",
"at": 1793750960,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
}
}
}client.removed客户被删除到回收站——删除前的样子
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.removed",
"at": 1793751100,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
}
}
}client.restored客户从回收站恢复
{
"id": "evt_mV3xQ8rT2kLp",
"event": "client.restored",
"at": 1793751160,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"id": "c_Ab3dE5fG7hJ9",
"name": "order-88123",
"status": "on",
"until": 1796342400,
"external": "88123",
"tags": ["paid", "month"],
"group": "",
"devices": 3,
"held": 2,
"left": { "days": 30, "bytes": null },
"…": "…"
}
}
}device.added客户添加了设备:该设备首次请求订阅——系统和应用
{
"id": "evt_mV3xQ8rT2kLp",
"event": "device.added",
"at": 1793751000,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"name": "order-88123",
"external": "88123",
"tags": ["paid", "month"],
"group": ""
},
"device": { "id": "a1b2c3d4e5f6", "kind": "app", "os": "iOS", "app": "Happ" }
}
}device.refused超出上限的设备被拒——每个客户每天最多一次:正好推荐再加一台设备
{
"id": "evt_mV3xQ8rT2kLp",
"event": "device.refused",
"at": 1793751200,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"name": "order-88123",
"external": "88123",
"tags": ["paid", "month"],
"group": ""
},
"device": {
"id": "f6e5d4c3b2a1",
"kind": "app",
"os": "Android",
"app": "v2rayNG"
}
}
}device.removed设备被解绑
{
"id": "evt_mV3xQ8rT2kLp",
"event": "device.removed",
"at": 1793751260,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"client": {
"name": "order-88123",
"external": "88123",
"tags": ["paid", "month"],
"group": ""
},
"device": { "id": "a1b2c3d4e5f6", "kind": "app", "os": "iOS", "app": "Happ" }
}
}node.silent节点 150 秒没有发送报告。被您停用的节点不算“无响应”
{
"id": "evt_mV3xQ8rT2kLp",
"event": "node.silent",
"at": 1793754000,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"node": { "name": "nl-1", "host": "198.51.100.20", "seen": 1793753850 }
}
}node.back无响应的节点恢复了联系
{
"id": "evt_mV3xQ8rT2kLp",
"event": "node.back",
"at": 1793754300,
"v": 1,
"panel": "https://panel.example.com",
"data": {
"node": { "name": "nl-1", "host": "198.51.100.20", "seen": 1793754295 }
}
}数据中的 client 与客户列表中的字段相同,不含链接。面板服务停止期间(最多 7 天)错过的 client.expiring、client.expired 和 client.reset 会在服务启动后发出;提醒只针对尚未到期的期限。
校验签名
请求头为 Veli-Signature: t=<时间>,v1=<签名>。签名是用 Webhook 密钥对字符串“<时间>.<请求体>”计算的 HMAC-SHA256,其中请求体是收到时的原始字节,在解析 JSON 之前。时间与您的时钟相差超过 5 分钟时,请丢弃该请求:这是旧请求的重放。
按原样取请求体
原始字节,在解析 JSON 之前:解析后再重新序列化,空格和字段顺序都会变,签名就对不上了。
计算 HMAC-SHA256
密钥是 Webhook 密钥,文本是请求头中的 t、一个点和请求体。用常数时间比较与 v1 对照。
核对时间
t 与您的时钟相差超过 5 分钟——丢弃:有人在重放旧请求。
import hashlib, hmac, time
def veli_signed(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
return False
want = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, v1)
# Flask: veli_signed(SECRET, request.headers["Veli-Signature"], request.get_data())import { createHmac, timingSafeEqual } from "node:crypto";
export function veliSigned(secret, header, body /* Buffer: the raw body */, tolerance = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > tolerance) return false;
const want = createHmac("sha256", secret).update(`${parts.t}.`).update(body).digest();
const got = Buffer.from(parts.v1 ?? "", "hex");
return got.length === want.length && timingSafeEqual(got, want);
}
// Express: app.post("/veli/events", express.raw({ type: "application/json" }), (req, res) => {
// if (!veliSigned(SECRET, req.get("veli-signature") ?? "", req.body)) return res.sendStatus(400);
// res.sendStatus(204);
// handle(JSON.parse(req.body));
// });用于核对:密钥 whsec_test,t=1762170000,请求体 {"id":"evt_1"} ——签名 5cfac9a08721cef8104f26838e60f410913d716e5b9fa59a32a196071cc5363c。