Integrazione Webhooks con TSplus Remote Support

Panoramica

I webhook ti consentono di collegare TSplus Remote Support ai tuoi sistemi (ticketing, CRM, SIEM, strumenti interni). Quando si verifica un evento nel tuo abbonamento, Remote Support invia un HTTP POST richiesta — contenente un payload JSON che descrive l'evento — a un URL che controlli.

Ogni richiesta è firmato crittograficamente in modo che il tuo server possa verificare che provenga realmente da Remote Support e non sia stato manomesso.

Casi d'uso tipici:

• Crea o aggiorna automaticamente un ticket quando termina una sessione di supporto.
• Archivia le trascrizioni delle chat di sessione nel tuo storage.
• Attiva notifiche interne o flussi di lavoro automatizzati.

Prerequisiti

Per configurare i webhook, assicurati di avere:

• Un abbonamento amministratore account.
• Un accesso pubblico HTTPS endpoint in grado di ricevere POST richieste.
• La possibilità di leggere le intestazioni delle richieste HTTP e il corpo della richiesta grezzo sul tuo server (richiesto per verificare la firma).

Configurare un webhook

1. Apri il TSplus Remote Support console di amministrazione.

2. Nel menu a sinistra, espandi Integrazione e fai clic Webhook .

   

3. Clicca Aggiungi un webhook .

   

4. Compila il modulo:

   • URL — l'endpoint HTTPS che riceverà gli eventi.
   • Descrizione opzionale — un'etichetta per aiutarti a identificare questo endpoint.
   • Eventi — seleziona almeno un tipo di evento a cui iscriverti.

5. Clicca Salva .

   

6. A segreto è generato e visualizzato una volta Copia ora e conservala in modo sicuro: viene utilizzata per verificare la firma delle richieste in arrivo e non verrà mostrata di nuovo.

   

Sicurezza: Per la tua protezione, l'URL viene convalidato quando lo salvi. Gli endpoint che puntano a localhost o gli indirizzi IP privati/interni vengono rifiutati.

Gestire i tuoi webhook

Dall'elenco dei Webhook puoi:

• Invia un evento di prova (icona del flask) — mette in coda una consegna di esempio in modo da poter confermare che il tuo endpoint riceve e accetta le richieste.
• Modifica (icona della matita) — modifica l'URL, la descrizione, gli eventi a cui sei iscritto o abilita/disabilita il punto finale.
• Elimina (icona del cestino) — rimuovere permanentemente l'endpoint.

Ogni endpoint mostra un stato :

• Attivo — l'endpoint è abilitato e riceve eventi.
• Disabilitato — l'endpoint è stato disabilitato manualmente.
• Auto-disabilitato — Il supporto remoto ha disabilitato automaticamente l'endpoint dopo 10 consegne consecutive non riuscite Correggi l'endpoint e riattivalo dal modulo di modifica.

Per ispezionare i singoli tentativi di consegna, filtrare gli eventi passati o riprovare una consegna non riuscita, vedere Tracciamento della consegna del Webhook .

Formato del payload

Ogni evento viene consegnato come un POST richiesta con un corpo JSON e i seguenti intestazioni:

Tutti gli eventi condividono un involucro comune. Solo il contenuto di dati cambiamenti a seconda del tipo di evento:

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

sessione avviata

Inviato quando viene creata una nuova sessione di supporto (il primo agente si connette a un 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"
  }
}

sessione.terminata

Inviato quando termina una sessione di supporto (tutti i partecipanti disconnessi). Il payload include la trascrizione completa della chat raccolta durante la sessione.

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

è_chiusura_anormale è vero solo quando una sessione viene chiusa dalla piattaforma dopo un riavvio imprevisto del relay. In quel caso il trascrizione_chat è vuoto.

partecipante.unito

Inviato quando un agente si unisce a una sessione.

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

partecipante.sinistra

Inviato quando un agente lascia una sessione. durata_secondi è da quanto tempo l'agente è stato connesso.

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

non sorvegliato.connesso

Inviato quando una sessione viene stabilita tramite accesso non presidiato (un agente che si connette con una password a un computer già online, a differenza di un utente attivo che condivide manualmente il proprio schermo). Si attiva esattamente come sessione avviata , ma solo per sessioni di accesso non presidiato. nome_utente identifica l'agente che si connette.

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

disconnesso.non sorvegliato

Inviato quando termina una sessione di accesso non presidiato (tutti i partecipanti disconnessi). Si attiva esattamente come sessione.terminata , ma solo per le sessioni di accesso non presidiato; nessun singolo partecipante è attribuito poiché la sessione nel suo insieme termina. durata_secondi è durata la sessione.

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

file trasferito

Inviato quando un file viene trasferito durante una sessione. Solo metadata viene inviato — il contenuto del file non viene mai memorizzato né trasmesso. direzione è caricare agente per macchina remota o scarica macchina remota all'agente. nome_utente identifica l'agente e potrebbe essere vuoto quando un download non può essere attribuito a un singolo agente.

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

Verifica della firma

Il tuo endpoint dovrebbe sempre verificare la firma prima di fidarsi di una richiesta. Chiunque conosca il tuo URL potrebbe altrimenti inviare eventi falsi; senza il segreto, non possono produrre una firma valida.

Per verificare una richiesta:

1. Leggi il corpo della richiesta grezza (i byte esatti ricevuti — non rieseguire la serializzazione del JSON).
2. Calcola HMAC-SHA256(rawBody, yourSecret) e codificarlo in esadecimale.
3. Prefissalo con sha256= e confrontalo con il X-Webhook-Signature intestazione utilizzando un confronto a tempo costante.

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

Consegna e ripetizioni

• Il tuo endpoint dovrebbe rispondere con un 2xx codice di stato il prima possibile. La richiesta scade dopo 10 secondi .
• Se una consegna fallisce, il Supporto Remoto riprova con un programma di backoff esponenziale: 10s, 30s, 1min, 5min, 15min, 1h, 4h, 24h (fino a 8 tentativi in 24 ore).
• I tentativi avvengono in caso di errori di connessione, HTTP 429 e 5xx risposte. Altro 4xx le risposte vengono trattate come errori permanenti e sono non ritentato.
• Dopo 10 consegne consecutive non riuscite l'endpoint è disabilitato automaticamente .

Per evitare di elaborare lo stesso evento due volte (ad esempio dopo un tentativo di ripetizione), utilizzare il X-Webhook-Id header (o il id campo nel payload) come chiave di idempotenza.

Eventi disponibili