Webhooks
Auf dieser Seite 9 Abschnitte
Ein Webhook veranlasst Localtonet, eine URL von Ihnen aufzurufen, wenn sich ein Gerät (AuthToken) oder ein Tunnel verbindet oder trennt. Nutzen Sie ihn, um Ihr Team zu benachrichtigen, einen Dienst neu zu starten oder Ihre eigene Statusseite aktuell zu halten.
So funktioniert es #
- Ein Webhook gehört zu einer Token-Gruppe. Er überwacht je nach Ihrer Wahl die AuthTokens dieser Gruppe, die Tunnel dieser Tokens oder beides.
- Wenn sich der Zustand eines überwachten Tokens oder Tunnels auf verbunden oder getrennt ändert, sendet Localtonet eine HTTP-
POST-Anfrage mit einem kleinen JSON-Body an Ihre URL. - Sie wählen, welches der beiden Ereignisse Sie möchten: Verbindung, Trennung oder beides.
Bevor Sie beginnen #
- Eine Token-Gruppe, die die AuthTokens enthält, die Sie überwachen möchten. Gruppen erstellen Sie unter Meine Tokens; siehe AuthTokens.
- Ein HTTP- oder HTTPS-Endpunkt, der aus dem Internet erreichbar ist und eine
POST-Anfrage mit einem JSON-Body annimmt. - Das Dashboard Ihres eigenen Kontos. Der Menüpunkt Webhooks wird nicht angezeigt, solange Sie in einem Team-Dashboard arbeiten.
Einen Webhook erstellen #
-
Webhooks öffnen #
Öffnen Sie Webhooks im Dashboard-Menü.
-
Wählen, worüber Sie informiert werden #
Einstellung Funktion Token-Webhook aktivieren Sendet eine Anfrage, wenn sich ein AuthToken der Gruppe verbindet oder trennt, das heißt, wenn der Localtonet-Client dieses Geräts online oder offline geht. Tunnel-Webhook aktivieren Sendet eine Anfrage, wenn sich ein Tunnel verbindet oder trennt, der zu einem AuthToken der Gruppe gehört. Bei Verbindung senden Sendet die Anfrage bei der Änderung auf „verbunden“. Bei Trennung senden Sendet die Anfrage bei der Änderung auf „getrennt“. Auth-Token-Gruppe Die zu überwachende Token-Gruppe. Erforderlich. Webhook-URL Die Adresse, die Localtonet aufruft. Erforderlich. Schalten Sie mindestens einen der beiden Webhook-Typen und mindestens einen der beiden Benachrichtigungstypen ein.
-
Erstellen #
Wählen Sie Erstellen. Der Webhook erscheint in der Liste unter dem Formular.
Die Webhook-Liste #
Jede Zeile zeigt Token-Webhook, Tunnel-Webhook, Gruppenname, URL, Bei Verbindung benachrichtigen und Bei Trennung benachrichtigen, jeden Schalter als Aktiv oder Passiv. Die Löschen-Schaltfläche in der Spalte Aktion entfernt den Webhook nach Ihrer Bestätigung.
Ein Webhook lässt sich nicht bearbeiten. Um seine URL, Gruppe oder Schalter zu ändern, löschen Sie ihn und erstellen Sie einen neuen. Sie können mehrere Webhooks für dieselbe Gruppe erstellen, zum Beispiel eine URL für Verbindungen und eine andere für Trennungen.
Die Anfrage, die Localtonet sendet #
| Teil | Wert |
|---|---|
| Methode | POST |
| Inhaltstyp | application/json; charset=utf-8 |
| Body | Ein JSON-Objekt mit den vier unten genannten Feldern. |
| Feld | Bedeutung | Werte |
|---|---|---|
Id | Kennzeichnet das Token oder den Tunnel, auf den sich das Ereignis bezieht. | Bei Type Token: kennzeichnet den AuthToken. Bei Type Tunnel: die numerische ID des Tunnels, als String gesendet. Es ist dieselbe ID, die die API als tunnelId verwendet. |
ActionDate | Wann Localtonet die Änderung registriert hat. | Datum und Uhrzeit im ISO-8601-Format |
Type | Die Art des Objekts. | Token oder Tunnel |
Status | Der neue Zustand. | Connected oder Disconnected |
Ein Token-Ereignis:
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}Ein Tunnel-Ereignis:
{
"Id": "<TUNNEL_ID>",
"ActionDate": "2026-01-15T10:31:12.7654321+03:00",
"Type": "Tunnel",
"Status": "Connected"
}Zustellung #
- Ein fehlgeschlagener Aufruf wird nicht wiederholt, daher sollte Ihr Endpunkt verfügbar sein und schnell antworten.
- Die Anfrage enthält keine Signatur und keinen Secret-Header. Um sicherzustellen, dass ein Aufruf von Ihrem Webhook stammt, fügen Sie der URL einen langen Zufallswert hinzu, zum Beispiel als Pfadsegment oder Abfrageparameter, und prüfen Sie ihn in Ihrem Empfänger.
- Eine Trennung wird gemeldet, wenn Localtonet registriert, dass der Client weg ist. Das kann etwas später sein als der Moment, in dem das Gerät seine Verbindung verloren hat.
- Parsen Sie
ActionDatemit einem Standard-ISO-8601-Parser und verwenden Sie den enthaltenen Offset; gehen Sie nicht von einer festen Zeitzone aus.
Beispiel eines Empfängers #
Jedes Webframework funktioniert. Der Empfänger muss nur den JSON-Body lesen und mit einem Erfolgsstatus antworten. Eine minimale Version mit Node.js und ohne Abhängigkeiten:
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);Mit diesem Empfänger lautet die Webhook-URL https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.
Ihren Webhook testen #
- Legen Sie einen AuthToken eines Testgeräts in die Token-Gruppe des Webhooks.
- Starten Sie den Localtonet-Client auf diesem Gerät mit dem Token. Ist Bei Verbindung senden eingeschaltet, erhält Ihr Endpunkt
TypeToken,StatusConnected. - Beenden Sie den Client mit Ctrl + C. Ihr Endpunkt erhält
StatusDisconnected. - Ist Tunnel-Webhook aktivieren eingeschaltet, starten und stoppen Sie unter Meine Tunnel einen Tunnel dieses Tokens, um die Tunnel-Ereignisse zu erhalten.
Noch kein öffentlicher Endpunkt? Führen Sie den Empfänger auf Ihrem Computer aus und veröffentlichen Sie ihn mit einem Localtonet-HTTP-Tunnel auf einem anderen AuthToken als dem, den Sie überwachen. Der Anfrage-Inspektor des Tunnels zeigt dann jeden Webhook-Aufruf; siehe Protokolle und Inspektion.
Fehlerbehebung #
„Aktivieren Sie mindestens einen Webhook-Typ.“ oder „Aktivieren Sie mindestens einen Benachrichtigungstyp.“
Schalten Sie Token-Webhook aktivieren oder Tunnel-Webhook aktivieren sowie Bei Verbindung senden oder Bei Trennung senden ein, bevor Sie Erstellen wählen.
„Gruppe ist erforderlich!“
Wählen Sie unter Auth-Token-Gruppe eine Token-Gruppe aus. Ist die Liste leer, erstellen Sie unter Meine Tokens eine Gruppe und fügen Sie Ihre Tokens hinzu.
Es kommt keine Anfrage an
Prüfen Sie, ob der AuthToken des Geräts Mitglied der Gruppe ist, die der Webhook überwacht, ob die passenden Schalter in der Liste Aktiv zeigen und ob die URL aus dem Internet erreichbar ist (nicht localhost oder eine private Adresse). Testen Sie die URL selbst:
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"}'Ich erhalte Token-Ereignisse, aber keine Tunnel-Ereignisse
Tunnel-Webhook muss für den Webhook Aktiv sein, und der Tunnel muss zu einem AuthToken gehören, der in der Gruppe ist.