تكامل 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 عمليات تسليم فاشلة متتالية قم بإصلاح نقطة النهاية وإعادة تمكينها من نموذج التحرير.

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

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

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

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

انتهت الجلسة

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

{
  "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", "user_id": 42, "message": "Hello, how can I help you?" },
      { "timestamp": "2026-07-10T14:31:30Z", "sender": "client", "message": "My screen is black" }
    ]
  }
}

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

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

يجب على نقطة النهاية الخاصة بك دائمًا التحقق من التوقيع قبل الوثوق في الطلب. أي شخص يعرف عنوان 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 رأس (أو ال معرف حقل في الحمولة) كمفتاح عدم التكرار.

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

سيتم إضافة المزيد من أنواع الأحداث في الإصدارات المستقبلية.