Документация/Подключение/Своя панель/Вебхуки·8 / 9
Вебхуки
Панель сама шлёт POST с JSON на ваш адрес, когда что-то случилось. Вебхуков — до 20 на панель, у каждого свои события.
Добавьте вебхук в консоли
На сервере панели: veli webhook add <адрес> --events a,b,c (или --events all — все события; вебхуков до 20). Адрес — только https://, до 500 знаков: приёмник на домене — как есть, на IP со своим сертификатом — с его отпечатком в конце: #sha256=<отпечаток>.
Секрет
Консоль печатает номер вебхука и его секрет один раз — им ваш приёмник проверяет подпись. Потеряли — удалите вебхук и добавьте заново: у нового секрет другой.
Посмотреть и убрать
veli webhook list показывает вебхуки, 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>- Ответьте 2xx за 5 секунд — Тогда доставка закончена. Долгую работу делайте после ответа.
- Иначе — повтор, почти трое суток — Другой код, нет ответа, не соединиться, чужой сертификат — снова через 10 секунд, минуту, 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 дня и за день
{
"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/<имя>
{
"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=<подпись>. Подпись — HMAC-SHA256 секретом вебхука от строки «<время>.<тело>», где тело — байты запроса как пришли, до разбора JSON. Время расходится с вашим больше чем на 5 минут — отбросьте запрос: это повтор старого.
Возьмите тело как пришло
Сырые байты, до разбора JSON: после разбора и обратной сборки пробелы и порядок полей уже другие, и подпись не сойдётся.
Посчитайте HMAC-SHA256
Ключ — секрет вебхука, текст — 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.