Integração de Webhooks com TSplus Remote Support

Visão geral

Webhooks permitem que você conecte TSplus Remote Support aos seus próprios sistemas (ticketing, CRM, SIEM, ferramentas internas). Quando um evento acontece na sua assinatura, o Remote Support envia um HTTP POST solicitação — contendo um payload JSON descrevendo o evento — para uma URL que você controla.

Cada solicitação é assinada criptograficamente para que seu servidor possa verificar se realmente vem do Remote Support e não foi adulterado.

Casos de uso típicos:

• Crie ou atualize automaticamente um ticket quando uma sessão de suporte termina.
• Arquive as transcrições de chat de sessão em seu próprio armazenamento.
• Acione notificações internas ou fluxos de trabalho de automação.

Pré-requisitos

Para configurar webhooks, certifique-se de que você tenha:

• Uma assinatura administrador conta.
• Um acesso público HTTPS endpoint capaz de receber POST solicitações.
• A capacidade de ler os cabeçalhos de solicitação HTTP e o corpo da solicitação bruta em seu servidor (necessário para verificar a assinatura).

Configurando um webhook

1. Abra o TSplus Remote Support console de administração.

2. No menu à esquerda, expanda Integração e clique Webhooks .

   

3. Clique Adicionar um webhook .

   

4. Preencha o formulário:

   • URL — o endpoint HTTPS que receberá os eventos.
   • Descrição opcional — uma etiqueta para ajudá-lo a identificar este ponto final.
   • Eventos — selecione pelo menos um tipo de evento para se inscrever.

5. Clique Salvar .

   

6. A segredo é gerado e exibido uma vez Copie-o agora e armazene-o com segurança — ele é usado para verificar a assinatura de solicitações recebidas e não será exibido novamente.

   

Segurança: Para sua proteção, a URL é validada quando você a salva. Os pontos finais apontando para localhost ou endereços IP privados/internos são rejeitados.

Gerenciando seus webhooks

Da lista de Webhooks, você pode:

• Enviar um evento de teste ícone de frasco — coloca em fila uma entrega de amostra para que você possa confirmar se seu endpoint recebe e aceita solicitações.
• Editar (ícone de lápis) — altere a URL, descrição, eventos inscritos ou ative/desative o endpoint.
• Excluir (ícone de lixo) — remover permanentemente o endpoint.

Cada endpoint mostra um status :

• Ativo — o endpoint está habilitado e recebendo eventos.
• Desativado — o endpoint foi desativado manualmente.
• Desativado automaticamente — O Suporte Remoto desativou automaticamente o endpoint após 10 entregas consecutivas falhadas Corrija o endpoint e reative-o a partir do formulário de edição.

Para inspecionar tentativas de entrega individuais, filtrar eventos passados ou tentar novamente uma entrega falhada, veja Rastreamento de Entrega de Webhook .

Formato de carga útil

Cada evento é entregue como um POST solicitação com um corpo JSON e os seguintes cabeçalhos:

Todos os eventos compartilham um envelope comum. Apenas o conteúdo de dados mudanças dependendo do tipo de evento:

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

sessão.iniciada

Enviado quando uma nova sessão de suporte é criada (o primeiro agente se conecta a um computador).

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

sessão.terminada

Enviado quando uma sessão de suporte termina (todos os participantes desconectados). O conteúdo inclui a transcrição completa do chat coletada durante a sessão.

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

é_fechamento_anormal é verdadeiro somente quando uma sessão é encerrada pela plataforma após uma reinicialização inesperada do relé. Nesse caso, o transcrição_do_chat está vazio.

participante.juntou-se

Enviado quando um agente entra em uma sessão.

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

participante.esquerda

Enviado quando um agente sai de uma sessão. duração_segundos é quanto tempo aquele agente esteve conectado.

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

não assistido.conectado

Enviado quando uma sessão é estabelecida através de acesso não supervisionado (um agente se conectando com uma senha a um computador que já está online, em oposição a um usuário ao vivo compartilhando manualmente sua tela). Ele dispara exatamente como sessão.iniciada , mas apenas para sessões de acesso não supervisionadas. nome_de_usuario identifica o agente que está se conectando.

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

desconectado.sem supervisão

Enviado quando uma sessão de acesso não supervisionado termina (todos os participantes desconectados). Ele é acionado exatamente como sessão.terminada , mas apenas para sessões de acesso não supervisionado; nenhum participante único é atribuído, uma vez que a sessão como um todo termina. duração_segundos é quanto tempo a sessão durou.

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

arquivo.transferido

Enviado quando um arquivo é transferido durante uma sessão. Apenas metadados é enviado — o conteúdo do arquivo nunca é armazenado nem transmitido. direção é upload (agent para máquina remota) ou download (máquina remota para agente). nome_de_usuario identifica o agente e pode estar vazio quando um download não pode ser atribuído a um único 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"
  }
}

Verificando a assinatura

Seu endpoint deve sempre verificar a assinatura antes de confiar em uma solicitação. Qualquer pessoa que conheça sua URL poderia, de outra forma, enviar eventos falsos; sem o segredo, não podem produzir uma assinatura válida.

Para verificar um pedido:

1. Leia o corpo da solicitação bruta (os bytes exatos recebidos — não reserialize o JSON).
2. Calcular HMAC-SHA256(rawBody, seuSegredo) e codificá-lo em hexadecimal.
3. Prefixe com sha256= e compare-o com o X-Webhook-Signature cabeçalho usando uma comparação em tempo constante.

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

Entrega e tentativas

• Seu endpoint deve responder com um 2xx código de status o mais rápido possível. O pedido expira após 10 segundos .
• Se uma entrega falhar, o Suporte Remoto tenta novamente com um cronograma de retrocesso exponencial: 10s, 30s, 1min, 5min, 15min, 1h, 4h, 24h (até 8 tentativas em 24 horas).
• As tentativas ocorrem em erros de conexão, HTTP 429 e, e 5xx respostas. Outro 4xx as respostas são tratadas como falhas permanentes e são não tentou novamente.
• Depois 10 entregas consecutivas falhadas o endpoint é automaticamente desativado .

Para evitar o processamento do mesmo evento duas vezes (por exemplo, após uma nova tentativa), use o X-Webhook-Id cabeçalho (ou o id campo na carga útil) como uma chave de idempotência.

Eventos disponíveis