Naar de inhoud
Localtonet Localtonet Dashboard

Webhooks

Hulp bij deze pagina
Op deze pagina 9 secties
  1. Hoe het werkt
  2. Voordat je begint
  3. Een webhook aanmaken
  4. Open Webhooks
  5. Kies waarover je bericht wilt krijgen
  6. Aanmaken
  7. De webhooklijst
  8. Het verzoek dat Localtonet verstuurt
  9. Aflevering
  10. Voorbeeldontvanger
  11. Je webhook testen
  12. Probleemoplossing
  13. Gerelateerde pagina's

Met een webhook laat je Localtonet een URL van jou aanroepen wanneer een apparaat (AuthToken) of een tunnel verbinding maakt of verbreekt. Gebruik het om je team te waarschuwen, een service te herstarten of je eigen statuspagina actueel te houden.

Hoe het werkt #

  • Een webhook hoort bij een tokengroep. Hij volgt de AuthTokens in die groep, de tunnels van die tokens, of beide, zoals jij kiest.
  • Wanneer de status van een gevolgde token of tunnel verandert naar verbonden of verbroken, stuurt Localtonet een HTTP-POST-verzoek met een kleine JSON-body naar je URL.
  • Je kiest welke van de twee gebeurtenissen je wilt: verbonden, verbroken, of beide.

Voordat je begint #

  • Een tokengroep met de AuthTokens die je wilt volgen. Maak groepen aan onder Mijn tokens; zie AuthTokens.
  • Een HTTP- of HTTPS-eindpunt dat vanaf internet bereikbaar is en een POST-verzoek met een JSON-body accepteert.
  • Het dashboard van je eigen account. Het menu-item Webhooks wordt niet getoond terwijl je in een teamdashboard werkt.

Een webhook aanmaken #

  1. Open Webhooks #

    Open Webhooks in het dashboardmenu.

  2. Kies waarover je bericht wilt krijgen #

    InstellingWat het doet
    Token-webhook inschakelenStuurt een verzoek wanneer een AuthToken van de groep verbinding maakt of verbreekt, dat wil zeggen wanneer de Localtonet-client van dat apparaat online of offline gaat.
    Tunnel-webhook inschakelenStuurt een verzoek wanneer een tunnel die bij een AuthToken van de groep hoort, verbinding maakt of verbreekt.
    Versturen bij verbindenStuurt het verzoek bij de wijziging naar verbonden.
    Versturen bij verbrekenStuurt het verzoek bij de wijziging naar verbroken.
    AuthToken-groepDe tokengroep die wordt gevolgd. Verplicht.
    Webhook-URLHet adres dat Localtonet aanroept. Verplicht.

    Schakel minstens een van de twee webhooktypen in en minstens een van de twee meldingstypen.

  3. Aanmaken #

    Kies Aanmaken. De webhook verschijnt in de lijst onder het formulier.

De webhooklijst #

Elke rij toont Token-webhook, Tunnel-webhook, Groepsnaam, URL, Melding bij verbinden en Melding bij verbreken, elke schakelaar als Actief of Inactief. De verwijderknop in de kolom Actie verwijdert de webhook nadat je dat bevestigt.

Een webhook kan niet worden bewerkt. Om de URL, groep of schakelaars te wijzigen, verwijder je hem en maak je een nieuwe aan. Je kunt meerdere webhooks voor dezelfde groep maken, bijvoorbeeld een URL voor verbindingen en een andere voor verbrekingen.

Het verzoek dat Localtonet verstuurt #

OnderdeelWaarde
MethodePOST
Inhoudstypeapplication/json; charset=utf-8
BodyEen JSON-object met de vier onderstaande velden.
VeldBetekenisWaarden
IdIdentificeert de token of tunnel waarop de gebeurtenis betrekking heeft.Bij Type Token: identificeert de AuthToken. Bij Type Tunnel: het numerieke ID van de tunnel, verstuurd als string. Het is hetzelfde ID dat de API gebruikt als tunnelId.
ActionDateWanneer Localtonet de wijziging heeft geregistreerd.Datum en tijd in ISO 8601-notatie
TypeHet soort object.Token of Tunnel
StatusDe nieuwe status.Connected of Disconnected

Een tokengebeurtenis:

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

Een tunnelgebeurtenis:

Verzoekbody
{
  "Id": "<TUNNEL_ID>",
  "ActionDate": "2026-01-15T10:31:12.7654321+03:00",
  "Type": "Tunnel",
  "Status": "Connected"
}

Aflevering #

  • Een mislukte aanroep wordt niet herhaald, dus je eindpunt moet beschikbaar zijn en snel antwoorden.
  • Het verzoek heeft geen handtekening of geheime header. Om zeker te weten dat een aanroep van jouw webhook komt, zet je een lange willekeurige waarde in de URL, bijvoorbeeld als padsegment of queryparameter, en controleer je die in je ontvanger.
  • Een verbreking wordt gemeld wanneer Localtonet registreert dat de client weg is, wat iets later kan zijn dan het moment waarop het apparaat de verbinding verloor.
  • Verwerk ActionDate met een standaard ISO 8601-parser en gebruik de offset die erin zit; ga niet uit van een vaste tijdzone.

Voorbeeldontvanger #

Elk webframework werkt. De ontvanger hoeft alleen de JSON-body te lezen en te antwoorden met een successtatus. Een minimale versie met Node.js en zonder afhankelijkheden:

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

Met deze ontvanger is de Webhook-URL https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.

Je webhook testen #

  1. Zet één AuthToken van een testapparaat in de tokengroep van de webhook.
  2. Start de Localtonet-client op dat apparaat met de token. Als Versturen bij verbinden aan staat, ontvangt je eindpunt Type Token, Status Connected.
  3. Stop de client met Ctrl + C. Je eindpunt ontvangt Status Disconnected.
  4. Als Tunnel-webhook inschakelen aan staat, start en stop je onder Mijn tunnels een tunnel van die token om de tunnelgebeurtenissen te ontvangen.

Nog geen publiek eindpunt? Laat de ontvanger op je computer draaien en publiceer hem met een Localtonet-HTTP-tunnel op een andere AuthToken dan die je volgt. De verzoekinspecteur van de tunnel toont dan elke webhookaanroep; zie Logboeken en inspectie.

Probleemoplossing #

"Schakel minstens één webhooktype in." of "Schakel minstens één meldingstype in."

Zet Token-webhook inschakelen of Tunnel-webhook inschakelen aan, en Versturen bij verbinden of Versturen bij verbreken, voordat je Aanmaken kiest.

"Groep is verplicht!"

Kies een tokengroep onder AuthToken-groep. Als de lijst leeg is, maak dan een groep aan onder Mijn tokens en voeg je tokens eraan toe.

Er komt geen verzoek binnen

Controleer of de AuthToken van het apparaat lid is van de groep die de webhook volgt, of de bijbehorende schakelaars in de lijst Actief tonen en of de URL vanaf internet bereikbaar is (niet localhost of een privéadres). Test de URL zelf:

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"}'
Ik krijg tokengebeurtenissen maar geen tunnelgebeurtenissen

Tunnel-webhook moet Actief zijn voor de webhook, en de tunnel moet bij een AuthToken horen die in de groep zit.

Support