Vai al contenuto
Localtonet Localtonet Dashboard

Webhook

Aiuto su questa pagina
In questa pagina 9 sezioni
  1. Come funziona
  2. Prima di iniziare
  3. Crea un webhook
  4. Apri Webhook
  5. Scegli di cosa essere avvisato
  6. Crea
  7. L'elenco dei webhook
  8. La richiesta inviata da Localtonet
  9. Consegna
  10. Esempio di ricevitore
  11. Prova il tuo webhook
  12. Risoluzione dei problemi
  13. Pagine correlate

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 POST con 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 POST con 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 #

  1. Apri Webhook #

    Apri Webhook nel menu della dashboard.

  2. Scegli di cosa essere avvisato #

    ImpostazioneCosa fa
    Abilita webhook del tokenInvia 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 tunnelInvia una richiesta quando un tunnel che appartiene a un AuthToken del gruppo si connette o si disconnette.
    Invia alla connessioneInvia la richiesta per il passaggio a connesso.
    Invia alla disconnessioneInvia la richiesta per il passaggio a disconnesso.
    Gruppo di Auth TokenIl gruppo di token da controllare. Obbligatorio.
    URL del webhookL'indirizzo che Localtonet chiama. Obbligatorio.

    Attiva almeno uno dei due tipi di webhook e almeno uno dei due tipi di notifica.

  3. 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 #

ParteValore
MetodoPOST
Tipo di contenutoapplication/json; charset=utf-8
CorpoUn oggetto JSON con i quattro campi qui sotto.
CampoSignificatoValori
IdIdentifica 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.
ActionDateQuando Localtonet ha registrato il cambiamento.Data e ora in formato ISO 8601
TypeIl tipo di oggetto.Token o Tunnel
StatusIl nuovo stato.Connected o Disconnected

Un evento di token:

Corpo della richiesta
{
  "Id": "<YOUR_TOKEN>",
  "ActionDate": "2026-01-15T10:30:00.1234567+03:00",
  "Type": "Token",
  "Status": "Disconnected"
}

Un evento di tunnel:

Corpo della richiesta
{
  "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 ActionDate con 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:

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

Con questo ricevitore, l'URL del webhook è https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.

Prova il tuo webhook #

  1. Inserisci un AuthToken di un dispositivo di prova nel gruppo di token del webhook.
  2. Avvia il client Localtonet su quel dispositivo con il token. Se Invia alla connessione è attivo, il tuo endpoint riceve Type Token, Status Connected.
  3. Ferma il client con Ctrl + C. Il tuo endpoint riceve Status Disconnected.
  4. 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:

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"}'
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.

Supporto