Documentation/Connecting/Your own panel/Webhooks·8 / 9
Webhooks
The panel itself sends a POST with JSON to your address when something happens. Up to 20 webhooks per panel, each with its own events.
Add the webhook in the console
On the panel's server: veli webhook add <url> --events a,b,c (or --events all for every event; up to 20 webhooks). The address is https:// only, up to 500 characters: a receiver on a domain — as it is, on an IP with its own certificate — with its fingerprint at the end: #sha256=<fingerprint>.
The secret
The console prints the webhook's number and its secret once — your receiver checks the signature with it. Lost it? Remove the webhook and add it again: the new one has another secret.
See and remove
veli webhook list shows the webhooks, veli webhook remove <number or url> removes one: no more events go to it.
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>- Answer 2xx within 5 seconds — Then the delivery is done. Do long work after answering.
- Else — again, for almost three days — Another code, no answer, no connection, a wrong certificate — again in 10 seconds, a minute, 5 and 30 minutes, 2, 6 and 12 hours, a day and one more day. After the tenth try the event is dropped.
- Twice and out of order — An event may come twice if an answer got lost, and after the next one if it waited for a retry: know a repeat by id, the order by at.
Events
The events of clients and devices go out within a couple of seconds; the events of time — a term about to end and ended, traffic, a new period, a node silent or back — within 15 seconds. Three more are added: backup.late — no copy of the panel has gone out for over a day, and node.unreachable and node.reachable — a node is closed from a checking country and open again; all three are in --events all. Click an event to see the request body.
client.addedA client was added — through the API, MCP or by the command on the server
{
"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.extendedA term was changed: extended, shortened, set by a date, put off till the first connection. days — by how much (below zero — shortened, null — set otherwise), before — the old end
{
"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.expiringThere are days days left to the term's end: by default at 3 days and at 1 day
{
"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.expiredA term ended
{
"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_near80% or 95% of the period's traffic is used — each threshold once a period; percent — which
{
"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.limitedThe period's traffic is used up
{
"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.resetA new traffic period began
{
"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_useThe app's first request for the subscription: a waiting client's term began with it
{
"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.changedThe devices, speed, limit, count, group, external ID, tags, fields, note or contact changed; fields — which exactly
{
"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.relinkedA new link — take it through 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.disabledA client was turned off
{
"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.enabledA client was turned on
{
"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.removedA client was deleted to the trash — as it was
{
"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.restoredA client was restored from the trash
{
"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.addedA client added a device: its first request for the subscription — the system and the app
{
"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.refusedA device over the limit was not let in — no more than once a day per client: a reason to offer one more device
{
"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.removedA device was unbound
{
"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.silentA node sent no report for 150 seconds. A node you turned off does not go “silent”
{
"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.backA silent node is in touch again
{
"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 in the data has the same fields as the list of clients, with no link. The client.expiring, client.expired and client.reset events missed while the panel's service was down (up to 7 days) come after it starts; a reminder is only about a term that has not ended yet.
Checking the signature
The header is Veli-Signature: t=<time>,v1=<signature>. The signature is HMAC-SHA256 with the webhook's secret of the string “<time>.<body>”, where the body is the request's bytes as they came, before the JSON is parsed. If the time is more than 5 minutes off yours, drop the request: it is an old one replayed.
Take the body as it came
Raw bytes, before the JSON is parsed: after parsing and building it back, the spaces and the order of fields differ, and the signature will not match.
Count the HMAC-SHA256
The key is the webhook's secret, the text is t from the header, a dot and the body. Compare it with v1 by a constant-time comparison.
Check the time
t is more than 5 minutes off your clock — drop it: someone is replaying an old request.
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));
// });To compare: the secret whsec_test, t=1762170000, the body {"id":"evt_1"} — the signature 5cfac9a08721cef8104f26838e60f410913d716e5b9fa59a32a196071cc5363c.