Webhook
In questa pagina 9 sezioni
Un webhook fa sì che Localtonet chiami un tuo URL quando un dispositivo (AuthToken) o un tunnel si connette o si disconnette. Usalo per avvisare il tuo team, riavviare un servizio o tenere aggiornata la tua pagina di stato.
Come funziona #
- Un webhook appartiene a un gruppo di token. Controlla gli AuthToken di quel gruppo, i tunnel di quei token, o entrambi, come scegli tu.
- Quando lo stato di un token o di un tunnel controllato passa a connesso o disconnesso, Localtonet invia al tuo URL una richiesta HTTP
POSTcon un piccolo corpo JSON. - Scegli quale dei due eventi vuoi: connessione, disconnessione, o entrambi.
Prima di iniziare #
- Un gruppo di token che contiene gli AuthToken che vuoi controllare. Crea i gruppi in I miei token; vedi AuthToken.
- Un endpoint HTTP o HTTPS raggiungibile da internet che accetti una richiesta
POSTcon un corpo JSON. - La dashboard del tuo account personale. La voce di menu Webhook non viene mostrata mentre lavori nella dashboard di un team.
Crea un webhook #
-
Apri Webhook #
Apri Webhook nel menu della dashboard.
-
Scegli di cosa essere avvisato #
Impostazione Cosa fa Abilita webhook del token Invia una richiesta quando un AuthToken del gruppo si connette o si disconnette, cioè quando il client Localtonet di quel dispositivo va online o offline. Abilita webhook del tunnel Invia una richiesta quando un tunnel che appartiene a un AuthToken del gruppo si connette o si disconnette. Invia alla connessione Invia la richiesta per il passaggio a connesso. Invia alla disconnessione Invia la richiesta per il passaggio a disconnesso. Gruppo di Auth Token Il gruppo di token da controllare. Obbligatorio. URL del webhook L'indirizzo che Localtonet chiama. Obbligatorio. Attiva almeno uno dei due tipi di webhook e almeno uno dei due tipi di notifica.
-
Crea #
Seleziona Crea. Il webhook compare nell'elenco sotto il modulo.
L'elenco dei webhook #
Ogni riga mostra Webhook del token, Webhook del tunnel, Nome del gruppo, URL, Notifica connessione e Notifica disconnessione, con ogni interruttore indicato come Attivo o Passivo. Il pulsante di eliminazione nella colonna Azione rimuove il webhook dopo la tua conferma.
Un webhook non si può modificare. Per cambiarne l'URL, il gruppo o gli interruttori, eliminalo e creane uno nuovo. Puoi creare più webhook per lo stesso gruppo, ad esempio un URL per le connessioni e un altro per le disconnessioni.
La richiesta inviata da Localtonet #
| Parte | Valore |
|---|---|
| Metodo | POST |
| Tipo di contenuto | application/json; charset=utf-8 |
| Corpo | Un oggetto JSON con i quattro campi qui sotto. |
| Campo | Significato | Valori |
|---|---|---|
Id | Identifica il token o il tunnel a cui si riferisce l'evento. | Per Type Token: identifica l'AuthToken. Per Type Tunnel: l'ID numerico del tunnel, inviato come stringa. È lo stesso ID che l'API usa come tunnelId. |
ActionDate | Quando Localtonet ha registrato il cambiamento. | Data e ora in formato ISO 8601 |
Type | Il tipo di oggetto. | Token o Tunnel |
Status | Il nuovo stato. | Connected o Disconnected |
Un evento di token:
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}Un evento di tunnel:
{
"Id": "<TUNNEL_ID>",
"ActionDate": "2026-01-15T10:31:12.7654321+03:00",
"Type": "Tunnel",
"Status": "Connected"
}Consegna #
- Una chiamata non riuscita non viene ripetuta, quindi il tuo endpoint dovrebbe essere disponibile e rispondere rapidamente.
- La richiesta non ha una firma né un header segreto. Per essere sicuro che una chiamata provenga dal tuo webhook, inserisci un lungo valore casuale nell'URL, ad esempio come segmento del percorso o parametro di query, e controllalo nel tuo ricevitore.
- Una disconnessione viene segnalata quando Localtonet registra che il client non c'è più, il che può avvenire un po' dopo il momento in cui il dispositivo ha perso la connessione.
- Analizza
ActionDatecon un parser ISO 8601 standard e usa l'offset che porta; non dare per scontato un fuso orario fisso.
Esempio di ricevitore #
Va bene qualsiasi framework web. Il ricevitore deve solo leggere il corpo JSON e rispondere con uno stato di successo. Una versione minima con Node.js e senza dipendenze:
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);Con questo ricevitore, l'URL del webhook è https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.
Prova il tuo webhook #
- Inserisci un AuthToken di un dispositivo di prova nel gruppo di token del webhook.
- Avvia il client Localtonet su quel dispositivo con il token. Se Invia alla connessione è attivo, il tuo endpoint riceve
TypeToken,StatusConnected. - Ferma il client con Ctrl + C. Il tuo endpoint riceve
StatusDisconnected. - Se Abilita webhook del tunnel è attivo, avvia e ferma un tunnel di quel token in I miei tunnel per ricevere gli eventi del tunnel.
Non hai ancora un endpoint pubblico? Esegui il ricevitore sul tuo computer e pubblicalo con un tunnel HTTP Localtonet su un AuthToken diverso da quello che stai controllando. L'ispettore delle richieste del tunnel mostra allora ogni chiamata del webhook; vedi Log e ispezione.
Risoluzione dei problemi #
"Attiva almeno un tipo di webhook." oppure "Attiva almeno un tipo di notifica."
Attiva Abilita webhook del token o Abilita webhook del tunnel, e Invia alla connessione o Invia alla disconnessione, prima di selezionare Crea.
"Il gruppo è obbligatorio!"
Seleziona un gruppo di token sotto Gruppo di Auth Token. Se l'elenco è vuoto, crea un gruppo in I miei token e aggiungici i tuoi token.
Non arriva nessuna richiesta
Controlla che l'AuthToken del dispositivo sia membro del gruppo controllato dal webhook, che gli interruttori corrispondenti mostrino Attivo nell'elenco e che l'URL sia raggiungibile da internet (non localhost né un indirizzo privato). Prova tu stesso l'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"}'Ricevo eventi dei token ma nessun evento dei tunnel
Webhook del tunnel deve essere Attivo per il webhook, e il tunnel deve appartenere a un AuthToken che è nel gruppo.