与TSplus远程支持的Webhooks集成

概述

Webhooks 让您将 TSplus Remote Support 连接到您自己的系统（工单、客户关系管理、SIEM、内部工具）。当您的订阅中发生事件时，Remote Support 会发送一个 HTTP 发布 请求 — 包含描述事件的 JSON 负载 — 发送到您控制的 URL。

每个请求都是 加密签名 以便您的服务器可以验证它确实来自远程支持，并且没有被篡改。

典型使用案例：

• 自动创建或更新支持会话结束时的工单。
• 将会话聊天记录存档到您自己的存储中。
• 触发内部通知或自动化工作流程。

先决条件

要配置网络钩子，请确保您拥有：

• 订阅 管理员 账户。
• 一个公开可访问的 HTTPS 能够接收的终端 发布 请求。
• 在您的服务器上读取HTTP请求头和原始请求体的能力（验证签名所需）。

配置网络钩子

1. 打开 TSplus Remote Support 管理控制台。

2. 在左侧菜单中，展开 集成 并点击 网络钩子 .

   

3. 点击 添加一个网络钩子 .

   

4. 填写表格：

   • 网址 — 将接收事件的 HTTPS 端点。
   • 描述 可选的 — 一个标签，帮助您识别此端点。
   • 事件 — 至少选择一个事件类型以订阅。

5. 点击 保存 .

   

6. A 秘密 生成并显示 一次 请现在复制并安全存储它——它用于验证传入请求的签名，并且不会再次显示。

   

安全： 为了您的保护，保存时会验证 URL。指向的端点 本地主机 或私有/内部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" }
    ]
  }
}

异常关闭 是 真实 仅在平台因意外中继重启而关闭会话时。在这种情况下， 聊天记录 是空的。

参与者已加入

当代理加入会话时发送。

{
  "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-Webhook-Signature 使用常量时间比较的头部。

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);
}

Python

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 "")

交付和重试

• 您的终端应响应一个 2xx 尽快返回状态代码。请求 在10秒后超时 .
• 如果交付失败，远程支持将按照指数退避计划重试： 10秒, 30秒, 1分钟, 5分钟, 15分钟, 1小时, 4小时, 24小时 （在24小时内最多可尝试8次）。
• 在连接错误时会发生重试，HTTP 429 ，和 5xx 响应。其他 4xx 响应被视为永久性失败并且是 不 重试。
• 之后 10次连续失败交付 ，端点是 自动禁用 .

为了避免重复处理同一事件（例如在重试后），请使用该 X-Webhook-Id 标题（或） id 在有效负载中作为幂等性密钥的字段。

可用事件