Webhooks-Integration mit TSplus Remote Support

Übersicht

Webhooks ermöglichen es Ihnen, TSplus Remote Support mit Ihren eigenen Systemen (Ticketing, CRM, SIEM, internen Tools) zu verbinden. Wenn ein Ereignis in Ihrem Abonnement eintritt, sendet Remote Support eine HTTP POST Anfrage — die eine JSON-Nutzlast beschreibt, die das Ereignis an eine URL sendet, die Sie kontrollieren.

Jede Anfrage ist kryptografisch signiert damit Ihr Server überprüfen kann, dass es tatsächlich von Remote Support stammt und nicht manipuliert wurde.

Typische Anwendungsfälle:

• Automatisch ein Ticket erstellen oder aktualisieren, wenn eine Support-Sitzung endet.
• Archivieren Sie die Chatprotokolle der Sitzung in Ihrem eigenen Speicher.
• Interne Benachrichtigungen oder Automatisierungs-Workflows auslösen.

Voraussetzungen

Um Webhooks zu konfigurieren, stellen Sie sicher, dass Sie Folgendes haben:

• Ein Abonnement Administrator Konto.
• Ein öffentlich erreichbarer HTTPS Endpunkt, der empfangen kann POST Anfragen.
• Die Fähigkeit, HTTP-Anforderungsheader und den Rohanforderungstext auf Ihrem Server zu lesen (erforderlich, um die Signatur zu überprüfen).

Webhook konfigurieren

1. Öffnen Sie die TSplus Remote Support Admin-Konsole.

2. Im linken Menü erweitern Integration und klicken Webhooks .

   

3. Klicken Webhook hinzufügen .

   

4. Füllen Sie das Formular aus:

   • URL — der HTTPS-Endpunkt, der die Ereignisse empfangen wird.
   • Beschreibung (optional) — ein Label, um Ihnen zu helfen, diesen Endpunkt zu identifizieren.
   • Veranstaltungen — Wählen Sie mindestens einen Ereignistyp aus, um sich anzumelden.

5. Klicken Speichern .

   

6. A geheim wird generiert und angezeigt einmal Kopieren Sie es jetzt und speichern Sie es sicher — es wird verwendet, um die Signatur eingehender Anfragen zu überprüfen und wird nicht erneut angezeigt.

   

Sicherheit: Zu Ihrem Schutz wird die URL validiert, wenn Sie sie speichern. Endpunkte, die auf localhost oder private/interne IP-Adressen werden abgelehnt.

Verwalten Ihrer Webhooks

Aus der Liste der Webhooks können Sie:

• Senden Sie ein Testereignis (flask icon) — stellt eine Beispielübermittlung in die Warteschlange, damit Sie bestätigen können, dass Ihr Endpunkt Anfragen empfängt und akzeptiert.
• Bearbeiten (Bleistiftsymbol) — Ändern Sie die URL, Beschreibung, abonnierten Ereignisse oder aktivieren/deaktivieren Sie den Endpunkt.
• Löschen ( Papierkorb-Symbol ) — Endpunkt dauerhaft entfernen.

Jedes Endgerät zeigt ein Status :

• Aktiv — der Endpunkt ist aktiviert und empfängt Ereignisse.
• Deaktiviert — der Endpunkt wurde manuell deaktiviert.
• Automatisch deaktiviert — Remote Support hat den Endpunkt nach dem automatischen Deaktivieren deaktiviert 10 aufeinanderfolgende fehlgeschlagene Lieferungen Fixen Sie den Endpunkt und aktivieren Sie ihn erneut über das Bearbeitungsformular.

Um einzelne Lieferversuche zu überprüfen, vergangene Ereignisse zu filtern oder eine fehlgeschlagene Lieferung erneut zu versuchen, siehe Webhook-Lieferverfolgung .

Payload-Format

Jedes Ereignis wird als ein geliefert POST Anfrage mit einem JSON-Body und den folgenden Headern:

Alle Ereignisse teilen sich eine gemeinsame Hülle. Nur der Inhalt von Daten Änderungen abhängig von der Ereignisart:

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

Sitzung gestartet

Gesendet, wenn eine neue Support-Sitzung erstellt wird (der erste Agent verbindet sich mit einem Computer).

{
  "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"
  }
}

Sitzung.beendet

Gesendet, wenn eine Support-Sitzung endet (alle Teilnehmer getrennt). Die Nutzlast enthält das vollständige Chatprotokoll, das während der Sitzung gesammelt wurde.

{
  "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" }
    ]
  }
}

ist_abnormale_schließung ist wahr nur wenn eine Sitzung von der Plattform nach einem unerwarteten Relay-Neustart geschlossen wird. In diesem Fall wird die Chat-Protokoll ist leer.

Teilnehmer beigetreten

Gesendet, wenn ein Agent einer Sitzung beitritt.

{
  "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"
  }
}

Teilnehmer.links

Gesendet, wenn ein Agent eine Sitzung verlässt. Dauer_Sekunden wie lange dieser Agent verbunden war.

{
  "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"
  }
}

unbeaufsichtigt.verbunden

Gesendet, wenn eine Sitzung über den unbeaufsichtigten Zugriff (ein Agent, der sich mit einem Passwort mit einem bereits online befindlichen Computer verbindet, im Gegensatz zu einem aktiven Benutzer, der manuell seinen Bildschirm teilt) hergestellt wird. Es wird genau wie ausgelöst. Sitzung gestartet , aber nur für unbeaufsichtigte Zugriffssitzungen. Benutzername identifiziert den sich verbindenden Agenten.

{
  "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"
  }
}

unbeaufsichtigt.trennen

Sent when an unattended-access session ends (all participants disconnected). It fires exactly wie Sitzung.beendet , aber nur für unbeaufsichtigte Zugriffssitzungen; kein einzelner Teilnehmer wird zugeordnet, da die Sitzung als Ganzes endet. Dauer_Sekunden wie lange die Sitzung gedauert hat.

{
  "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"
  }
}

Datei übertragen

Gesendet, wenn eine Datei während einer Sitzung übertragen wird. Nur Metadaten wird gesendet — der Dateinhalt wird niemals gespeichert oder übertragen. Richtung ist hochladen (agent zu entferntem Computer) oder Herunterladen (remote machine to agent). Benutzername identifiziert den Agenten und kann leer sein, wenn ein Download nicht einem einzelnen Agenten zugeordnet werden kann.

{
  "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"
  }
}

Die Signatur überprüfen

Ihr Endpunkt sollte immer die Signatur überprüfen, bevor er einer Anfrage vertraut. Jeder, der Ihre URL kennt, könnte sonst gefälschte Ereignisse senden; ohne das Geheimnis können sie keine gültige Signatur erzeugen.

Um eine Anfrage zu überprüfen:

1. Lies die roher Anfragekörper (die genauen empfangenen Bytes — das JSON nicht erneut serialisieren).
2. Berechnen HMAC-SHA256(rawBody, yourSecret) und hex-kodieren Sie es.
3. Prefix es mit sha256= und vergleichen Sie es mit dem X-Webhook-Signatur Header, der einen Vergleich in konstanter Zeit verwendet.

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

Lieferung und Wiederholungen

• Ihr Endpunkt sollte mit einem antworten 2xx Statuscode so schnell wie möglich. Die Anfrage nach 10 Sekunden abgelaufen .
• Wenn eine Lieferung fehlschlägt, versucht der Remote Support es mit einem exponentiellen Backoff-Zeitplan erneut: 10s, 30s, 1min, 5min, 15min, 1h, 4h, 24h (maximal 8 Versuche über 24 Stunden).
• Wiederholungen treten bei Verbindungsfehlern auf, HTTP 429 und 5xx Antworten. Andere 4xx Antworten werden als dauerhafte Fehler behandelt und sind nicht wiederholt.
• Nach 10 aufeinanderfolgende fehlgeschlagene Lieferungen , der Endpunkt ist automatisch deaktiviert .

Um zu vermeiden, dass dasselbe Ereignis zweimal verarbeitet wird (zum Beispiel nach einem erneuten Versuch), verwenden Sie die X-Webhook-Id header (oder die id Feld im Payload als Idempotenzschlüssel.

Verfügbare Ereignisse