文档/如何接入/自建面板/Webhook·8 / 9

Webhook

发生事情时,面板会主动向您的地址发送带 JSON 的 POST 请求。每个面板最多 20 个 Webhook,每个有自己的事件。

  1. 在控制台添加 Webhook

    在面板服务器上运行:veli webhook add <地址> --events a,b,c(或 --events all 表示所有事件;最多 20 个 Webhook)。地址只能是 https://,不超过 500 个字符:域名上的接收端照原样填写;IP 上使用自签证书的接收端,在末尾加上证书指纹:#sha256=<指纹>。

  2. 密钥

    控制台只打印一次 Webhook 的编号和密钥——您的接收端用它校验签名。丢了?删除这个 Webhook 再重新添加:新的会有另一个密钥。

  3. 查看与删除

    veli webhook list 显示 Webhook,veli webhook remove <序号或地址> 删除其中一个:之后不再向它发送事件。

添加 Webhook:地址和事件
veli webhook add https://example.com/veli-hook --events client.added,client.expiring,client.expired
Webhook 列表,按序号或地址删除
veli webhook list
veli webhook remove 1
面板的请求
POST /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": {…}}}
IP 上接收端的证书指纹
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 分钟时,请丢弃该请求:这是旧请求的重放。

  1. 按原样取请求体

    原始字节,在解析 JSON 之前:解析后再重新序列化,空格和字段顺序都会变,签名就对不上了。

  2. 计算 HMAC-SHA256

    密钥是 Webhook 密钥,文本是请求头中的 t、一个点和请求体。用常数时间比较与 v1 对照。

  3. 核对时间

    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())

用于核对:密钥 whsec_test,t=1762170000,请求体 {"id":"evt_1"} ——签名 5cfac9a08721cef8104f26838e60f410913d716e5b9fa59a32a196071cc5363c。