Webhooks
Nesta página 9 seções
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
POSTcom 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
POSTcom 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 #
-
Abra Webhooks #
Abra Webhooks no menu do painel.
-
Escolha sobre o que ser avisado #
Configuração O que faz Ativar webhook de token Envia 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únel Envia uma requisição quando um túnel que pertence a um AuthToken do grupo se conecta ou se desconecta. Enviar ao conectar Envia a requisição para a mudança para conectado. Enviar ao desconectar Envia a requisição para a mudança para desconectado. Grupo de tokens de autenticação O grupo de tokens a observar. Obrigatório. URL do webhook O 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.
-
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 #
| Parte | Valor |
|---|---|
| Método | POST |
| Tipo de conteúdo | application/json; charset=utf-8 |
| Corpo | Um objeto JSON com os quatro campos abaixo. |
| Campo | Significado | Valores |
|---|---|---|
Id | Identifica 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. |
ActionDate | Quando o Localtonet registrou a mudança. | Data e hora no formato ISO 8601 |
Type | O tipo de objeto. | Token ou Tunnel |
Status | O novo estado. | Connected ou Disconnected |
Um evento de token:
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}Um evento de túnel:
{
"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
ActionDatecom 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:
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 #
- Coloque um AuthToken de um dispositivo de teste no grupo de tokens do webhook.
- Inicie o cliente Localtonet nesse dispositivo com o token. Se Enviar ao conectar estiver ativado, o seu endpoint recebe
TypeToken,StatusConnected. - Pare o cliente com Ctrl + C. O seu endpoint recebe
StatusDisconnected. - 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:
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.