تكامل Webhooks مع TSplus Remote Support

نظرة عامة

تتيح لك Webhooks ربط TSplus Remote Support بأنظمتك الخاصة (نظام التذاكر، إدارة علاقات العملاء، SIEM، الأدوات الداخلية). عندما يحدث حدث في اشتراكك، يرسل Remote Support طلب HTTP منشور طلب — يحتوي على حمولة JSON تصف الحدث — إلى عنوان URL تتحكم فيه.

كل طلب هو موقعياً موقعة حتى يتمكن خادمك من التحقق من أنه يأتي بالفعل من Remote Support ولم يتم العبث به.

حالات الاستخدام النموذجية:

• قم بإنشاء أو تحديث تذكرة تلقائيًا عند انتهاء جلسة الدعم.
• أرشفة نصوص محادثات الجلسة في تخزينك الخاص.
• قم بتفعيل الإشعارات الداخلية أو سير العمل الآلي.

المتطلبات الأساسية

لتكوين الويب هوكس، تأكد من أن لديك:

• اشتراك مدير الحساب.
• قابل للوصول علنًا HTTPS نقطة النهاية القادرة على الاستقبال منشور طلبات.
• القدرة على قراءة رؤوس طلبات HTTP وجسم الطلب الخام على خادمك (مطلوب للتحقق من التوقيع).

تكوين webhook

1. افتح الـ TSplus Remote Support وحدة التحكم الإدارية.

2. في القائمة اليسرى، قم بتوسيع تكامل وانقر ويب هوكس .

   

3. انقر أضف webhook .

   

4. املأ النموذج:

   • رابط — نقطة النهاية HTTPS التي ستستقبل الأحداث.
   • وصف اختياري — تسمية لمساعدتك في تحديد هذه النقطة النهائية.
   • الأحداث — اختر نوع حدث واحد على الأقل للاشتراك فيه.

5. انقر احفظ .

   

6. أ سرّ يتم إنشاؤه وعرضه مرة واحدة انسخه الآن واحتفظ به بأمان - يُستخدم للتحقق من توقيع الطلبات الواردة ولن يتم عرضه مرة أخرى.

   

الأمان: لحمايتك، يتم التحقق من صحة عنوان URL عند حفظه. النقاط النهائية التي تشير إلى localhost أو يتم رفض عناوين IP الخاصة/الداخلية.

إدارة الويب هوكس

من قائمة Webhooks يمكنك:

• أرسل حدث اختبار (رمز القارورة) — يضيف طلب تسليم عينة حتى تتمكن من تأكيد أن نقطة النهاية الخاصة بك تستقبل وتقبل الطلبات.
• تعديل (رمز القلم) — تغيير عنوان URL، الوصف، الأحداث المشترك فيها، أو تمكين/تعطيل نقطة النهاية.
• احذف (رمز سلة المهملات) — إزالة نقطة النهاية بشكل دائم.

كل نقطة نهاية تظهر الحالة :

• نشط — نقطة النهاية مفعلة وتتلقى الأحداث.
• معطل — تم تعطيل نقطة النهاية يدويًا.
• تم تعطيله تلقائيًا — تم تعطيل الدعم عن بُعد تلقائيًا للنقطة النهائية بعد 10 عمليات تسليم فاشلة متتالية قم بإصلاح نقطة النهاية وإعادة تمكينها من نموذج التحرير.

للاطلاع على محاولات التسليم الفردية، وتصنيف الأحداث السابقة، أو إعادة محاولة تسليم فاشلة، راجع تتبع تسليم Webhook .

تنسيق الحمولة

يتم تسليم كل حدث كـ منشور طلب مع جسم JSON والرؤوس التالية:

تشارك جميع الأحداث غلافًا مشتركًا. فقط محتوى بيانات تتغير حسب نوع الحدث:

{
  "id": "evt_abc123def456",
  "type": "session.ended",
  "created_at": "2026-07-10T15:00:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": { }
}

تم بدء الجلسة

يتم الإرسال عند إنشاء جلسة دعم جديدة (عندما يتصل الوكيل الأول بجهاز كمبيوتر).

{
  "id": "evt_abc123def456",
  "type": "session.started",
  "created_at": "2026-07-10T14:30:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "computer_name": "Front-desk PC",
    "started_at": "2026-07-10T14:30:00Z"
  }
}

انتهت الجلسة

يتم إرساله عند انتهاء جلسة الدعم (تم فصل جميع المشاركين). تتضمن الحمولة نص الدردشة الكامل الذي تم جمعه خلال الجلسة.

{
  "id": "evt_xyz789ghi012",
  "type": "session.ended",
  "created_at": "2026-07-10T15:00:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "computer_name": "Front-desk PC",
    "started_at": "2026-07-10T14:30:00Z",
    "ended_at": "2026-07-10T15:00:00Z",
    "duration_seconds": 1800,
    "is_abnormal_closure": false,
    "chat_transcript": [
      { "timestamp": "2026-07-10T14:31:00Z", "sender": "agent", "message": "Hello, how can I help you?" },
      { "timestamp": "2026-07-10T14:31:30Z", "sender": "client", "message": "My screen is black" }
    ]
  }
}

إغلاق غير طبيعي هو صحيح فقط عندما يتم إغلاق جلسة بواسطة المنصة بعد إعادة تشغيل غير متوقعة لل relay. في هذه الحالة، الـ نص المحادثة فارغ.

انضم المشارك

يتم الإرسال عند انضمام وكيل إلى جلسة.

{
  "id": "evt_join789abc",
  "type": "participant.joined",
  "created_at": "2026-07-10T14:32:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "user_name": "Jane Doe",
    "joined_at": "2026-07-10T14:32:00Z"
  }
}

المشارك.يسار

يتم الإرسال عندما يغادر وكيل الجلسة. مدة_الثواني مدة اتصال الوكيل.

{
  "id": "evt_left456def",
  "type": "participant.left",
  "created_at": "2026-07-10T14:37:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "user_name": "Jane Doe",
    "duration_seconds": 300,
    "left_at": "2026-07-10T14:37:00Z"
  }
}

غير متصل.

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

{
  "id": "evt_unatt123on",
  "type": "unattended.connected",
  "created_at": "2026-07-10T14:30:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "computer_name": "Front-desk PC",
    "user_name": "Jane Doe",
    "connected_at": "2026-07-10T14:30:00Z"
  }
}

غير متصل بدون مراقبة

يتم إرساله عند انتهاء جلسة الوصول غير المراقب (تم فصل جميع المشاركين). يتم تشغيله تمامًا مثل انتهت الجلسة ، ولكن فقط لجلسات الوصول غير المراقب؛ لا يُنسب أي مشارك واحد لأن الجلسة ككل تنتهي. مدة_الثواني مدة الجلسة.

{
  "id": "evt_unatt456off",
  "type": "unattended.disconnected",
  "created_at": "2026-07-10T15:30:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "computer_name": "Front-desk PC",
    "duration_seconds": 3600,
    "disconnected_at": "2026-07-10T15:30:00Z"
  }
}

تم نقل الملف

يتم إرساله عند نقل ملف أثناء جلسة. فقط بيانات التعريف يتم إرسال — محتوى الملف لا يتم تخزينه أو نقله أبداً. الاتجاه هو رفع (وكيل إلى الجهاز البعيد) أو تحميل (جهاز بعيد إلى وكيل). اسم المستخدم يحدد الوكيل، وقد يكون فارغًا عندما لا يمكن نسب التنزيل إلى وكيل واحد.

{
  "id": "evt_file456abc",
  "type": "file.transferred",
  "created_at": "2026-07-10T14:45:00Z",
  "subscription_key": "XXXX-XXXX-XXXX",
  "data": {
    "remote_support_id": "ABC123",
    "user_name": "Jane Doe",
    "file_name": "diagnostic.zip",
    "file_size_bytes": 2048576,
    "direction": "download",
    "timestamp": "2026-07-10T14:45:00Z"
  }
}

التحقق من التوقيع

يجب على نقطة النهاية الخاصة بك دائمًا التحقق من التوقيع قبل الوثوق في الطلب. أي شخص يعرف عنوان URL الخاص بك يمكنه إرسال أحداث مزيفة؛ بدون السر، لا يمكنهم إنتاج توقيع صالح.

للتحقق من الطلب:

1. اقرأ الـ نص الطلب الخام (بايتات البيانات المستلمة بالضبط - لا تعيد تسلسل JSON).
2. احسب HMAC-SHA256(rawBody, yourSecret) وهي ترميزها بتنسيق هيكس.
3. قم بإضافته مسبقًا sha256= وقارنها بـ توقيع الويب X رأس باستخدام مقارنة زمن ثابت.

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

بايثون

import hmac
import hashlib

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

التسليم وإعادة المحاولة

• يجب أن يستجيب نقطة النهاية الخاصة بك بـ ٢xx رمز الحالة في أسرع وقت ممكن. الطلب ينتهي بعد 10 ثوانٍ .
• إذا فشلت عملية التسليم، فإن الدعم عن بُعد يعيد المحاولة وفق جدول زمني بتراجع أسي: 10 ثوانٍ، 30 ثانية، 1 دقيقة، 5 دقائق، 15 دقيقة، 1 ساعة، 4 ساعات، 24 ساعة (حتى 8 محاولات خلال 24 ساعة).
• تحدث المحاولات عند حدوث أخطاء في الاتصال، HTTP 429 ، و ٥xx الردود. أخرى ٤٠٠ تُعتبر الردود فشلاً دائماً ويتم ليس أعيد المحاولة.
• بعد 10 عمليات تسليم فاشلة متتالية نقطة النهاية هي معطل تلقائيًا .

لتجنب معالجة نفس الحدث مرتين (على سبيل المثال بعد إعادة المحاولة)، استخدم الـ معرف-ويب هوك-X رأس (أو ال معرف حقل في الحمولة) كمفتاح عدم التكرار.

الأحداث المتاحة