与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次连续失败的交付 修复端点并从编辑表单重新启用它。

有效负载格式

每个事件都作为一个 发布 请求带有 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" }
    ]
  }
}

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

验证签名

您的终端在信任请求之前应始终验证签名。否则，任何知道您 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 在有效负载中作为幂等性密钥的字段。

可用事件

未来版本将添加更多事件类型。