Документация/Подключение/Своя панель/Вебхуки·8 / 9

Вебхуки

Панель сама шлёт POST с JSON на ваш адрес, когда что-то случилось. Вебхуков — до 20 на панель, у каждого свои события.

  1. Добавьте вебхук в консоли

    На сервере панели: veli webhook add <адрес> --events a,b,c (или --events all — все события; вебхуков до 20). Адрес — только https://, до 500 знаков: приёмник на домене — как есть, на IP со своим сертификатом — с его отпечатком в конце: #sha256=<отпечаток>.

  2. Секрет

    Консоль печатает номер вебхука и его секрет один раз — им ваш приёмник проверяет подпись. Потеряли — удалите вебхук и добавьте заново: у нового секрет другой.

  3. Посмотреть и убрать

    veli webhook list показывает вебхуки, veli webhook remove <номер или адрес> убирает вебхук: события на него больше не шлются.

Добавить вебхук: адрес и события
veli webhook add https://example.com/veli-hook --events client.added,client.expiring,client.expired
Список вебхуков и удаление по номеру или адресу
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>
  • Ответьте 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 минут — отбросьте запрос: это повтор старого.

  1. Возьмите тело как пришло

    Сырые байты, до разбора JSON: после разбора и обратной сборки пробелы и порядок полей уже другие, и подпись не сойдётся.

  2. Посчитайте HMAC-SHA256

    Ключ — секрет вебхука, текст — 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.