انتقل إلى المحتوى
Localtonet Localtonet لوحة التحكم

Webhooks

مساعدة بشأن هذه الصفحة
في هذه الصفحة 9 أقسام
  1. كيف يعمل
  2. قبل أن تبدأ
  3. أنشئ webhook
  4. افتح Webhooks
  5. اختر ما تريد أن تُبلَّغ به
  6. إنشاء
  7. قائمة الـ webhooks
  8. الطلب الذي ترسله Localtonet
  9. التسليم
  10. مثال على مستقبِل
  11. اختبر الـ webhook
  12. استكشاف الأخطاء وإصلاحها
  13. صفحات ذات صلة

يجعل الـ webhook خدمة Localtonet تستدعي رابطًا خاصًا بك عندما يتصل جهاز (AuthToken) أو نفق أو ينقطع اتصاله. استخدمه لتنبيه فريقك، أو لإعادة تشغيل خدمة، أو لإبقاء صفحة الحالة الخاصة بك محدّثة.

كيف يعمل #

  • ينتمي الـ webhook إلى مجموعة توكنات. وهو يراقب AuthToken في تلك المجموعة، أو أنفاق تلك التوكنات، أو كليهما، بحسب اختيارك.
  • عندما تتغير حالة توكن أو نفق مراقَب إلى متصل أو منقطع، ترسل Localtonet طلب HTTP من نوع POST بجسم JSON صغير إلى رابطك.
  • أنت تختار أي الحدثين تريد: الاتصال أو قطع الاتصال أو كليهما.

قبل أن تبدأ #

  • مجموعة توكنات تحتوي AuthToken التي تريد مراقبتها. أنشئ المجموعات ضمن توكناتي؛ راجع AuthToken.
  • نقطة نهاية HTTP أو HTTPS يمكن الوصول إليها من الإنترنت وتقبل طلب POST بجسم JSON.
  • لوحة تحكم حسابك الخاص. لا يظهر عنصر القائمة Webhooks أثناء عملك في لوحة تحكم فريق.

أنشئ webhook #

  1. افتح Webhooks #

    افتح Webhooks من قائمة لوحة التحكم.

  2. اختر ما تريد أن تُبلَّغ به #

    الإعدادما يفعله
    تفعيل Webhook التوكناتيرسل طلبًا عندما يتصل AuthToken في المجموعة أو ينقطع اتصاله، أي عندما يعمل عميل Localtonet على ذلك الجهاز أو يتوقف.
    تفعيل Webhook الأنفاقيرسل طلبًا عندما يتصل نفق ينتمي إلى AuthToken في المجموعة أو ينقطع اتصاله.
    الإرسال عند الاتصاليرسل الطلب عند التغيّر إلى متصل.
    الإرسال عند قطع الاتصاليرسل الطلب عند التغيّر إلى منقطع.
    مجموعة توكنات المصادقةمجموعة التوكنات المراد مراقبتها. مطلوبة.
    رابط Webhookالعنوان الذي تستدعيه Localtonet. مطلوب.

    فعّل نوعًا واحدًا على الأقل من نوعي Webhook ونوع إشعار واحدًا على الأقل من نوعي الإشعار.

  3. إنشاء #

    اضغط إنشاء. يظهر الـ webhook في القائمة أسفل النموذج.

قائمة الـ webhooks #

يعرض كل صف Webhook التوكنات وWebhook الأنفاق واسم المجموعة والرابط وإشعار الاتصال وإشعار قطع الاتصال، وكل مفتاح بصيغة نشط أو غير نشط. ويزيل زر الحذف في عمود الإجراء الـ webhook بعد أن تؤكد.

لا يمكن تعديل الـ webhook. لتغيير رابطه أو مجموعته أو مفاتيحه، احذفه وأنشئ واحدًا جديدًا. ويمكنك إنشاء عدة webhooks للمجموعة نفسها، مثلًا رابط واحد للاتصال وآخر لقطع الاتصال.

الطلب الذي ترسله Localtonet #

الجزءالقيمة
الطريقةPOST
نوع المحتوىapplication/json; charset=utf-8
الجسمكائن JSON بالحقول الأربعة أدناه.
الحقلالمعنىالقيم
Idيحدّد التوكن أو النفق الذي يخصه الحدث.عندما يكون Type هو Token: يحدّد AuthToken. وعندما يكون Type هو Tunnel: المعرّف الرقمي للنفق، يُرسل كسلسلة نصية. وهو المعرّف نفسه الذي يستخدمه API بصيغة tunnelId.
ActionDateوقت تسجيل Localtonet للتغيير.التاريخ والوقت بصيغة ISO 8601
Typeنوع الكائن.Token أو Tunnel
Statusالحالة الجديدة.Connected أو Disconnected

حدث توكن:

جسم الطلب
{
  "Id": "<YOUR_TOKEN>",
  "ActionDate": "2026-01-15T10:30:00.1234567+03:00",
  "Type": "Token",
  "Status": "Disconnected"
}

حدث نفق:

جسم الطلب
{
  "Id": "<TUNNEL_ID>",
  "ActionDate": "2026-01-15T10:31:12.7654321+03:00",
  "Type": "Tunnel",
  "Status": "Connected"
}

التسليم #

  • لا يُعاد الاستدعاء الفاشل، لذا يجب أن تكون نقطة النهاية لديك متاحة وأن ترد بسرعة.
  • لا يحتوي الطلب على توقيع أو ترويسة سرّ. للتأكد من أن الاستدعاء صادر عن webhook الخاص بك، ضع قيمة عشوائية طويلة في الرابط، مثلًا كجزء من المسار أو كمعامل استعلام، وتحقق منها في المستقبِل لديك.
  • يُبلَّغ عن قطع الاتصال عندما تسجّل Localtonet أن العميل قد غاب، وقد يكون ذلك متأخرًا قليلًا عن لحظة فقدان الجهاز اتصاله.
  • حلّل ActionDate بمحلّل ISO 8601 قياسي واستخدم الإزاحة التي يحملها؛ ولا تفترض منطقة زمنية ثابتة.

مثال على مستقبِل #

يصلح أي إطار عمل ويب. يكفي أن يقرأ المستقبِل جسم JSON وأن يرد بحالة نجاح. نسخة مبسطة بـ Node.js ودون أي اعتمادات:

receiver.js
const http = require('http');

http.createServer((req, res) => {
  let body = '';
  req.on('data', chunk => body += chunk);
  req.on('end', () => {
    if (req.method === 'POST' && req.url === '/localtonet/<YOUR_SECRET>') {
      const event = JSON.parse(body);
      console.log(event.Type, event.Status, event.ActionDate);
    }
    res.writeHead(200);
    res.end();
  });
}).listen(8080);

مع هذا المستقبِل يكون رابط Webhook هو https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.

اختبر الـ webhook #

  1. ضع أحد AuthToken الخاصة بجهاز اختبار في مجموعة التوكنات الخاصة بالـ webhook.
  2. شغّل عميل Localtonet على ذلك الجهاز بالتوكن. إذا كان الإرسال عند الاتصال مفعّلًا، تتلقى نقطة النهاية لديك Type بالقيمة Token وStatus بالقيمة Connected.
  3. أوقف العميل بالضغط على Ctrl + C. تتلقى نقطة النهاية لديك Status بالقيمة Disconnected.
  4. إذا كان تفعيل Webhook الأنفاق مفعّلًا، فشغّل نفقًا يخص ذلك التوكن وأوقفه ضمن أنفاقي للحصول على أحداث الأنفاق.

ليست لديك نقطة نهاية عامة بعد؟ شغّل المستقبِل على حاسوبك وانشره عبر نفق HTTP من Localtonet بـ AuthToken مختلف عن الذي تراقبه. يعرض مفتش الطلبات الخاص بالنفق حينئذٍ كل استدعاء webhook؛ راجع السجلات والفحص.

استكشاف الأخطاء وإصلاحها #

«فعّل نوع Webhook واحدًا على الأقل.» أو «فعّل نوع إشعار واحدًا على الأقل.»

شغّل تفعيل Webhook التوكنات أو تفعيل Webhook الأنفاق، والإرسال عند الاتصال أو الإرسال عند قطع الاتصال، قبل أن تضغط إنشاء.

«المجموعة مطلوبة!»

اختر مجموعة توكنات ضمن مجموعة توكنات المصادقة. وإذا كانت القائمة فارغة، فأنشئ مجموعة ضمن توكناتي وأضف توكناتك إليها.

لا يصل أي طلب

تحقّق من أن AuthToken الخاص بالجهاز عضو في المجموعة التي يراقبها الـ webhook، وأن المفاتيح المطابقة تعرض نشط في القائمة، وأن الرابط يمكن الوصول إليه من الإنترنت (وليس localhost أو عنوانًا خاصًا). اختبر الرابط بنفسك:

Bash
curl -X POST "<YOUR_WEBHOOK_URL>" \
  -H "Content-Type: application/json" \
  -d '{"Id":"test","ActionDate":"2026-01-15T10:30:00+00:00","Type":"Token","Status":"Connected"}'
أتلقى أحداث التوكنات لكن لا أتلقى أحداث الأنفاق

يجب أن يكون Webhook الأنفاق بحالة نشط في الـ webhook، ويجب أن ينتمي النفق إلى AuthToken موجود في المجموعة.

الدعم