Webhooks
في هذه الصفحة 9 أقسام
يجعل الـ webhook خدمة Localtonet تستدعي رابطًا خاصًا بك عندما يتصل جهاز (AuthToken) أو نفق أو ينقطع اتصاله. استخدمه لتنبيه فريقك، أو لإعادة تشغيل خدمة، أو لإبقاء صفحة الحالة الخاصة بك محدّثة.
كيف يعمل #
- ينتمي الـ webhook إلى مجموعة توكنات. وهو يراقب AuthToken في تلك المجموعة، أو أنفاق تلك التوكنات، أو كليهما، بحسب اختيارك.
- عندما تتغير حالة توكن أو نفق مراقَب إلى متصل أو منقطع، ترسل Localtonet طلب HTTP من نوع
POSTبجسم JSON صغير إلى رابطك. - أنت تختار أي الحدثين تريد: الاتصال أو قطع الاتصال أو كليهما.
قبل أن تبدأ #
- مجموعة توكنات تحتوي AuthToken التي تريد مراقبتها. أنشئ المجموعات ضمن توكناتي؛ راجع AuthToken.
- نقطة نهاية HTTP أو HTTPS يمكن الوصول إليها من الإنترنت وتقبل طلب
POSTبجسم JSON. - لوحة تحكم حسابك الخاص. لا يظهر عنصر القائمة Webhooks أثناء عملك في لوحة تحكم فريق.
أنشئ webhook #
-
افتح Webhooks #
افتح Webhooks من قائمة لوحة التحكم.
-
اختر ما تريد أن تُبلَّغ به #
الإعداد ما يفعله تفعيل Webhook التوكنات يرسل طلبًا عندما يتصل AuthToken في المجموعة أو ينقطع اتصاله، أي عندما يعمل عميل Localtonet على ذلك الجهاز أو يتوقف. تفعيل Webhook الأنفاق يرسل طلبًا عندما يتصل نفق ينتمي إلى AuthToken في المجموعة أو ينقطع اتصاله. الإرسال عند الاتصال يرسل الطلب عند التغيّر إلى متصل. الإرسال عند قطع الاتصال يرسل الطلب عند التغيّر إلى منقطع. مجموعة توكنات المصادقة مجموعة التوكنات المراد مراقبتها. مطلوبة. رابط Webhook العنوان الذي تستدعيه Localtonet. مطلوب. فعّل نوعًا واحدًا على الأقل من نوعي Webhook ونوع إشعار واحدًا على الأقل من نوعي الإشعار.
-
إنشاء #
اضغط إنشاء. يظهر الـ 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 ودون أي اعتمادات:
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 #
- ضع أحد AuthToken الخاصة بجهاز اختبار في مجموعة التوكنات الخاصة بالـ webhook.
- شغّل عميل Localtonet على ذلك الجهاز بالتوكن. إذا كان الإرسال عند الاتصال مفعّلًا، تتلقى نقطة النهاية لديك
TypeبالقيمةTokenوStatusبالقيمةConnected. - أوقف العميل بالضغط على Ctrl + C. تتلقى نقطة النهاية لديك
StatusبالقيمةDisconnected. - إذا كان تفعيل Webhook الأنفاق مفعّلًا، فشغّل نفقًا يخص ذلك التوكن وأوقفه ضمن أنفاقي للحصول على أحداث الأنفاق.
ليست لديك نقطة نهاية عامة بعد؟ شغّل المستقبِل على حاسوبك وانشره عبر نفق HTTP من Localtonet بـ AuthToken مختلف عن الذي تراقبه. يعرض مفتش الطلبات الخاص بالنفق حينئذٍ كل استدعاء webhook؛ راجع السجلات والفحص.
استكشاف الأخطاء وإصلاحها #
«فعّل نوع Webhook واحدًا على الأقل.» أو «فعّل نوع إشعار واحدًا على الأقل.»
شغّل تفعيل Webhook التوكنات أو تفعيل Webhook الأنفاق، والإرسال عند الاتصال أو الإرسال عند قطع الاتصال، قبل أن تضغط إنشاء.
«المجموعة مطلوبة!»
اختر مجموعة توكنات ضمن مجموعة توكنات المصادقة. وإذا كانت القائمة فارغة، فأنشئ مجموعة ضمن توكناتي وأضف توكناتك إليها.
لا يصل أي طلب
تحقّق من أن AuthToken الخاص بالجهاز عضو في المجموعة التي يراقبها الـ webhook، وأن المفاتيح المطابقة تعرض نشط في القائمة، وأن الرابط يمكن الوصول إليه من الإنترنت (وليس localhost أو عنوانًا خاصًا). اختبر الرابط بنفسك:
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 موجود في المجموعة.