التوثيق/الاتصال/لوحتك الخاصة/خطافات الويب·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تغيّرت الأجهزة أو السرعة أو الحد أو العدّاد أو المجموعة أو المعرّف الخارجي أو الوسوم أو الحقول أو الملاحظة أو جهة الاتصال؛ و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 دقائق فاترك الطلب: إنه إعادة لطلب قديم.

  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.