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.

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.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", "user_id": 42, "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.

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

In future versions, more event types will be added.