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.

  1. 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>.

  2. 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.

  3. See and remove

    veli webhook list shows the webhooks, veli webhook remove <number or url> removes one: no more events go to it.

Add a webhook: the address and the events
veli webhook add https://example.com/veli-hook --events client.added,client.expiring,client.expired
The webhooks list and removing by number or address
veli webhook list
veli webhook remove 1
The panel's request
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": {…}}}
The fingerprint of a receiver's certificate on an IP
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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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>
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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
Request body
{
  "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”
Request body
{
  "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
Request body
{
  "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.

  1. 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.

  2. 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.

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

To compare: the secret whsec_test, t=1762170000, the body {"id":"evt_1"} — the signature 5cfac9a08721cef8104f26838e60f410913d716e5b9fa59a32a196071cc5363c.