TSplus 원격 지원과의 웹후크 통합

개요

웹후크를 사용하면 TSplus Remote Support를 귀하의 시스템(티켓팅, CRM, SIEM, 내부 도구)에 연결할 수 있습니다. 구독에서 이벤트가 발생하면 Remote Support가 HTTP를 전송합니다. 게시물 이벤트를 설명하는 JSON 페이로드를 포함하는 요청을 귀하가 제어하는 URL로 전송합니다.

각 요청은 암호학적으로 서명된 서버가 진정으로 Remote Support에서 온 것임을 확인하고 변조되지 않았음을 검증할 수 있도록 합니다.

일반적인 사용 사례:

• 지원 세션이 종료될 때 자동으로 티켓을 생성하거나 업데이트합니다.
• 세션 채팅 기록을 귀하의 저장소에 보관하십시오.
• 내부 알림 또는 자동화 워크플로를 트리거합니다.

필수 조건

웹훅을 구성하려면 다음을 확인하세요:

• 구독 관리자 계정.
• 공개적으로 접근 가능한 HTTPS 엔드포인트 수신 가능 게시물 요청.
• 서버에서 HTTP 요청 헤더와 원시 요청 본문을 읽는 기능(서명을 확인하는 데 필요).

웹훅 구성

1. 열기 TSplus Remote Support 관리 콘솔.

2. 왼쪽 메뉴에서 확장하십시오. 통합 그리고 클릭 웹후크 .

   

3. 클릭 웹후크 추가 .

   

4. 양식을 작성하십시오:

   • URL — 이벤트를 수신할 HTTPS 엔드포인트.
   • 설명 선택 사항 — 이 엔드포인트를 식별하는 데 도움이 되는 레이블입니다.
   • 이벤트 — 최소한 하나의 이벤트 유형을 선택하여 구독하세요.

5. 클릭 저장 .

   

6. A 비밀 생성되어 표시됩니다 한 번 지금 복사하여 안전하게 저장하세요 — 이는 들어오는 요청의 서명을 확인하는 데 사용되며 다시는 표시되지 않습니다.

   

보안: 귀하의 보호를 위해 URL이 저장할 때 검증됩니다. 포인팅된 엔드포인트 로컬호스트 사설/내부 IP 주소는 거부됩니다.

웹후크 관리

웹훅 목록에서 다음을 수행할 수 있습니다:

• 테스트 이벤트 보내기 (flask icon) — 샘플 배달을 대기열에 추가하여 엔드포인트가 요청을 수신하고 수락하는지 확인할 수 있습니다.
• 편집 (연필 아이콘) — URL, 설명, 구독한 이벤트를 변경하거나 엔드포인트를 활성화/비활성화합니다.
• 삭제 (휴지통 아이콘) — 엔드포인트를 영구적으로 제거합니다.

각 엔드포인트는 보여줍니다. 상태 :

• 활성 — 엔드포인트가 활성화되어 이벤트를 수신하고 있습니다.
• 비활성화됨 — 엔드포인트가 수동으로 비활성화되었습니다.
• 자동 비활성화 — 원격 지원이 엔드포인트를 자동으로 비활성화했습니다. 10회의 연속 실패한 배달 엔드포인트를 수정하고 편집 양식에서 다시 활성화하십시오.

개별 배달 시도를 검사하거나 과거 이벤트를 필터링하거나 실패한 배달을 재시도하려면 다음을 참조하십시오. 웹훅 배송 추적 .

페이로드 형식

모든 이벤트는 다음과 같이 제공됩니다. 게시물 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) 그리고 16진수로 인코딩합니다.
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 "")

배달 및 재시도

• 귀하의 엔드포인트는 다음과 같이 응답해야 합니다. 2xx 상태 코드를 가능한 한 빨리 요청하십시오. 10초 후에 시간 초과됩니다. .
• 배송이 실패하면, Remote Support는 지수 백오프 일정으로 재시도합니다. 10초, 30초, 1분, 5분, 15분, 1시간, 4시간, 24시간 (24시간 동안 최대 8회 시도)
• 연결 오류, HTTP에서 재시도가 발생합니다. 429 , 그리고 5xx 응답. 기타 4xx 응답은 영구적인 실패로 처리됩니다. 아니다 재시도했습니다.
• 후에 10회의 연속 실패한 배달 엔드포인트는 자동으로 비활성화됨 .

같은 이벤트를 두 번 처리하지 않도록 (예: 재시도 후) 사용하십시오. X-Webhook-Id 헤더 (또는 the) 아이디 페이로드의 필드) 아이덴포턴시 키로 사용됩니다.

사용 가능한 이벤트