التوثيق/الاتصال/لوحتك الخاصة/خطافات الويب·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تغيّرت الأجهزة أو السرعة أو الحد أو العدّاد أو المجموعة أو المعرّف الخارجي أو الوسوم أو الحقول أو الملاحظة أو جهة الاتصال؛ و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 في البيانات — حقول قائمة العملاء نفسها، بلا رابط. والأحداث client.expiring وclient.expired وclient.reset التي فاتت أثناء توقف خدمة اللوحة (حتى 7 أيام) تصل بعد تشغيلها؛ والتذكير — فقط عن مدة لم تنتهِ بعد.
التحقق من التوقيع
الترويسة 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.