Ir para o conteúdo
Localtonet Localtonet Painel

Webhooks

Ajuda com esta página
Nesta página 9 seções
  1. Como funciona
  2. Antes de começar
  3. Criar um webhook
  4. Abra Webhooks
  5. Escolha sobre o que ser avisado
  6. Criar
  7. A lista de webhooks
  8. A requisição que o Localtonet envia
  9. Entrega
  10. Exemplo de receptor
  11. Teste o seu webhook
  12. Solução de problemas
  13. Páginas relacionadas

Um webhook faz o Localtonet chamar uma URL sua quando um dispositivo (AuthToken) ou um túnel se conecta ou se desconecta. Use-o para alertar a sua equipe, reiniciar um serviço ou manter a sua própria página de status atualizada.

Como funciona #

  • Um webhook pertence a um grupo de tokens. Ele observa os AuthTokens desse grupo, os túneis desses tokens ou ambos, conforme você escolher.
  • Quando o estado de um token ou túnel observado muda para conectado ou desconectado, o Localtonet envia à sua URL uma requisição HTTP POST com um pequeno corpo JSON.
  • Você escolhe qual dos dois eventos quer: conectado, desconectado ou ambos.

Antes de começar #

  • Um grupo de tokens que contenha os AuthTokens que você quer observar. Crie grupos em Meus tokens; veja AuthTokens.
  • Um endpoint HTTP ou HTTPS acessível pela internet que aceite uma requisição POST com corpo JSON.
  • O painel da sua própria conta. O item de menu Webhooks não aparece enquanto você trabalha em um painel de equipe.

Criar um webhook #

  1. Abra Webhooks #

    Abra Webhooks no menu do painel.

  2. Escolha sobre o que ser avisado #

    ConfiguraçãoO que faz
    Ativar webhook de tokenEnvia uma requisição quando um AuthToken do grupo se conecta ou se desconecta, ou seja, quando o cliente Localtonet desse dispositivo fica online ou offline.
    Ativar webhook de túnelEnvia uma requisição quando um túnel que pertence a um AuthToken do grupo se conecta ou se desconecta.
    Enviar ao conectarEnvia a requisição para a mudança para conectado.
    Enviar ao desconectarEnvia a requisição para a mudança para desconectado.
    Grupo de tokens de autenticaçãoO grupo de tokens a observar. Obrigatório.
    URL do webhookO endereço que o Localtonet chama. Obrigatório.

    Ative pelo menos um dos dois tipos de webhook e pelo menos um dos dois tipos de notificação.

  3. Criar #

    Selecione Criar. O webhook aparece na lista abaixo do formulário.

A lista de webhooks #

Cada linha mostra Webhook de token, Webhook de túnel, Nome do grupo, URL, Aviso de conexão e Aviso de desconexão, cada interruptor como Ativo ou Inativo. O botão de excluir na coluna Ação remove o webhook depois que você confirma.

Um webhook não pode ser editado. Para alterar a URL, o grupo ou os interruptores, exclua-o e crie um novo. Você pode criar vários webhooks para o mesmo grupo, por exemplo uma URL para conexões e outra para desconexões.

A requisição que o Localtonet envia #

ParteValor
MétodoPOST
Tipo de conteúdoapplication/json; charset=utf-8
CorpoUm objeto JSON com os quatro campos abaixo.
CampoSignificadoValores
IdIdentifica o token ou túnel a que o evento se refere.Para Type Token: identifica o AuthToken. Para Type Tunnel: o ID numérico do túnel, enviado como string. É o mesmo ID que a API usa como tunnelId.
ActionDateQuando o Localtonet registrou a mudança.Data e hora no formato ISO 8601
TypeO tipo de objeto.Token ou Tunnel
StatusO novo estado.Connected ou Disconnected

Um evento de token:

Corpo da requisição
{
  "Id": "<YOUR_TOKEN>",
  "ActionDate": "2026-01-15T10:30:00.1234567+03:00",
  "Type": "Token",
  "Status": "Disconnected"
}

Um evento de túnel:

Corpo da requisição
{
  "Id": "<TUNNEL_ID>",
  "ActionDate": "2026-01-15T10:31:12.7654321+03:00",
  "Type": "Tunnel",
  "Status": "Connected"
}

Entrega #

  • Uma chamada com falha não é repetida, então o seu endpoint deve estar disponível e responder rápido.
  • A requisição não tem assinatura nem cabeçalho de segredo. Para ter certeza de que uma chamada vem do seu webhook, coloque um valor aleatório longo na URL, por exemplo como segmento de caminho ou parâmetro de consulta, e verifique-o no seu receptor.
  • Uma desconexão é informada quando o Localtonet registra que o cliente saiu, o que pode ser um pouco depois do momento em que o dispositivo perdeu a conexão.
  • Analise ActionDate com um parser ISO 8601 padrão e use o deslocamento que ele traz; não presuma um fuso horário fixo.

Exemplo de receptor #

Qualquer framework web serve. O receptor só precisa ler o corpo JSON e responder com um status de sucesso. Uma versão mínima com Node.js e sem dependências:

receiver.js
const http = require('http');

http.createServer((req, res) => {
  let body = '';
  req.on('data', chunk => body += chunk);
  req.on('end', () => {
    if (req.method === 'POST' && req.url === '/localtonet/<YOUR_SECRET>') {
      const event = JSON.parse(body);
      console.log(event.Type, event.Status, event.ActionDate);
    }
    res.writeHead(200);
    res.end();
  });
}).listen(8080);

Com este receptor, a URL do webhook é https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.

Teste o seu webhook #

  1. Coloque um AuthToken de um dispositivo de teste no grupo de tokens do webhook.
  2. Inicie o cliente Localtonet nesse dispositivo com o token. Se Enviar ao conectar estiver ativado, o seu endpoint recebe Type Token, Status Connected.
  3. Pare o cliente com Ctrl + C. O seu endpoint recebe Status Disconnected.
  4. Se Ativar webhook de túnel estiver ativado, inicie e pare um túnel desse token em Meus túneis para receber os eventos de túnel.

Ainda não tem um endpoint público? Execute o receptor no seu computador e publique-o com um túnel HTTP do Localtonet em um AuthToken diferente do que você está observando. O inspetor de requisições do túnel passa então a mostrar cada chamada de webhook; veja Logs e inspeção.

Solução de problemas #

"Ative pelo menos um tipo de webhook." ou "Ative pelo menos um tipo de notificação."

Ative Ativar webhook de token ou Ativar webhook de túnel, e Enviar ao conectar ou Enviar ao desconectar, antes de selecionar Criar.

"O grupo é obrigatório!"

Selecione um grupo de tokens em Grupo de tokens de autenticação. Se a lista estiver vazia, crie um grupo em Meus tokens e adicione seus tokens a ele.

Nenhuma requisição chega

Verifique se o AuthToken do dispositivo é membro do grupo que o webhook observa, se os interruptores correspondentes mostram Ativo na lista e se a URL é acessível pela internet (não localhost nem um endereço privado). Teste você mesmo a URL:

Bash
curl -X POST "<YOUR_WEBHOOK_URL>" \
  -H "Content-Type: application/json" \
  -d '{"Id":"test","ActionDate":"2026-01-15T10:30:00+00:00","Type":"Token","Status":"Connected"}'
Recebo eventos de token, mas nenhum evento de túnel

Webhook de túnel precisa estar Ativo no webhook, e o túnel precisa pertencer a um AuthToken que esteja no grupo.

Suporte