Webhooks
Sur cette page 9 sections
Un webhook fait appeler une de vos URL par Localtonet lorsqu'un appareil (AuthToken) ou un tunnel se connecte ou se déconnecte. Utilisez-le pour alerter votre équipe, redémarrer un service ou tenir à jour votre propre page d'état.
Fonctionnement #
- Un webhook appartient à un groupe de jetons. Il surveille les AuthToken de ce groupe, les tunnels de ces jetons, ou les deux, selon votre choix.
- Lorsque l'état d'un jeton ou d'un tunnel surveillé passe à connecté ou déconnecté, Localtonet envoie à votre URL une requête HTTP
POSTavec un petit corps JSON. - Vous choisissez lequel des deux événements vous intéresse : connexion, déconnexion, ou les deux.
Avant de commencer #
- Un groupe de jetons qui contient les AuthToken que vous voulez surveiller. Créez des groupes sous Mes jetons ; voir AuthToken.
- Un point d'accès HTTP ou HTTPS joignable depuis Internet et qui accepte une requête
POSTavec un corps JSON. - Le tableau de bord de votre propre compte. L'élément de menu Webhooks n'est pas affiché lorsque vous travaillez dans un tableau de bord d'équipe.
Créer un webhook #
-
Ouvrir Webhooks #
Ouvrez Webhooks dans le menu du tableau de bord.
-
Choisir ce dont vous voulez être informé #
Paramètre Fonction Activer le webhook de jeton Envoie une requête lorsqu'un AuthToken du groupe se connecte ou se déconnecte, c'est-à-dire lorsque le client Localtonet de cet appareil passe en ligne ou hors ligne. Activer le webhook de tunnel Envoie une requête lorsqu'un tunnel qui appartient à un AuthToken du groupe se connecte ou se déconnecte. Envoyer à la connexion Envoie la requête pour le passage à connecté. Envoyer à la déconnexion Envoie la requête pour le passage à déconnecté. Groupe de jetons d'authentification Le groupe de jetons à surveiller. Obligatoire. URL du webhook L'adresse que Localtonet appelle. Obligatoire. Activez au moins un des deux types de webhook et au moins un des deux types de notification.
-
Créer #
Sélectionnez Créer. Le webhook apparaît dans la liste sous le formulaire.
La liste des webhooks #
Chaque ligne affiche Webhook de jeton, Webhook de tunnel, Nom du groupe, URL, Notif. connexion et Notif. déconnexion, chaque interrupteur étant indiqué comme Actif ou Passif. Le bouton de suppression de la colonne Action supprime le webhook après confirmation.
Un webhook ne peut pas être modifié. Pour changer son URL, son groupe ou ses interrupteurs, supprimez-le et créez-en un nouveau. Vous pouvez créer plusieurs webhooks pour le même groupe, par exemple une URL pour les connexions et une autre pour les déconnexions.
La requête envoyée par Localtonet #
| Élément | Valeur |
|---|---|
| Méthode | POST |
| Type de contenu | application/json; charset=utf-8 |
| Corps | Un objet JSON avec les quatre champs ci-dessous. |
| Champ | Signification | Valeurs |
|---|---|---|
Id | Identifie le jeton ou le tunnel concerné par l'événement. | Pour Type Token : identifie l'AuthToken. Pour Type Tunnel : l'ID numérique du tunnel, envoyé sous forme de chaîne. C'est le même ID que celui que l'API utilise comme tunnelId. |
ActionDate | Le moment où Localtonet a enregistré le changement. | Date et heure au format ISO 8601 |
Type | Le type d'objet. | Token ou Tunnel |
Status | Le nouvel état. | Connected ou Disconnected |
Un événement de jeton :
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}Un événement de tunnel :
{
"Id": "<TUNNEL_ID>",
"ActionDate": "2026-01-15T10:31:12.7654321+03:00",
"Type": "Tunnel",
"Status": "Connected"
}Remise #
- Un appel qui échoue n'est pas répété ; votre point d'accès doit donc être disponible et répondre rapidement.
- La requête ne comporte ni signature ni en-tête secret. Pour vous assurer qu'un appel provient de votre webhook, placez une longue valeur aléatoire dans l'URL, par exemple comme segment de chemin ou paramètre de requête, et vérifiez-la dans votre récepteur.
- Une déconnexion est signalée lorsque Localtonet constate que le client a disparu, ce qui peut arriver un peu après le moment où l'appareil a perdu sa connexion.
- Analysez
ActionDateavec un analyseur ISO 8601 standard et utilisez le décalage qu'il contient ; ne supposez pas de fuseau horaire fixe.
Exemple de récepteur #
N'importe quel framework web convient. Le récepteur doit seulement lire le corps JSON et répondre avec un statut de réussite. Une version minimale avec Node.js et sans dépendances :
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);Avec ce récepteur, l'URL du webhook est https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.
Tester votre webhook #
- Placez un AuthToken d'un appareil de test dans le groupe de jetons du webhook.
- Démarrez le client Localtonet sur cet appareil avec le jeton. Si Envoyer à la connexion est activé, votre point d'accès reçoit
TypeToken,StatusConnected. - Arrêtez le client avec Ctrl + C. Votre point d'accès reçoit
StatusDisconnected. - Si Activer le webhook de tunnel est activé, démarrez et arrêtez un tunnel de ce jeton sous Mes tunnels pour recevoir les événements de tunnel.
Pas encore de point d'accès public ? Exécutez le récepteur sur votre ordinateur et publiez-le avec un tunnel HTTP Localtonet sur un AuthToken différent de celui que vous surveillez. L'inspecteur de requêtes du tunnel affiche alors chaque appel de webhook ; voir Journaux et inspection.
Dépannage #
« Activez au moins un type de webhook. » ou « Activez au moins un type de notification. »
Activez Activer le webhook de jeton ou Activer le webhook de tunnel, ainsi que Envoyer à la connexion ou Envoyer à la déconnexion, avant de sélectionner Créer.
« Le groupe est obligatoire ! »
Sélectionnez un groupe de jetons sous Groupe de jetons d'authentification. Si la liste est vide, créez un groupe sous Mes jetons et ajoutez-y vos jetons.
Aucune requête n'arrive
Vérifiez que l'AuthToken de l'appareil est membre du groupe que surveille le webhook, que les interrupteurs correspondants affichent Actif dans la liste, et que l'URL est joignable depuis Internet (pas localhost ni une adresse privée). Testez vous-même 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"}'Je reçois des événements de jeton mais aucun événement de tunnel
Webhook de tunnel doit être Actif pour le webhook, et le tunnel doit appartenir à un AuthToken qui fait partie du groupe.