Wannan shafin bai samu a cikin Hausa tukuna ba. Ana nuna shi da Turanci.
Webhooks
A wannan shafin 9 sassa
A webhook makes Localtonet call a URL of yours when a device (AuthToken) or a tunnel connects or disconnects. Use it to alert your team, restart a service, or keep your own status page up to date.
How it works #
- A webhook belongs to a token group. It watches the AuthTokens in that group, the tunnels of those tokens, or both, as you choose.
- When the state of a watched token or tunnel changes to connected or disconnected, Localtonet sends an HTTP
POSTrequest with a small JSON body to your URL. - You choose which of the two events you want: connected, disconnected, or both.
Before you start #
- A token group that contains the AuthTokens you want to watch. Create groups under My Tokens; see AuthTokens.
- An HTTP or HTTPS endpoint that is reachable from the internet and accepts a
POSTrequest with a JSON body. - Your own account dashboard. The Webhooks menu item is not shown while you work in a team dashboard.
Create a webhook #
-
Open Webhooks #
Open Webhooks in the dashboard menu.
-
Choose what to be told about #
Setting What it does Token Webhook Enable Sends a request when an AuthToken of the group connects or disconnects, that is, when the Localtonet client of that device comes online or goes offline. Tunnel Webhook Enable Sends a request when a tunnel that belongs to an AuthToken of the group connects or disconnects. Send When Connected Sends the request for the change to connected. Send When Disconnected Sends the request for the change to disconnected. Auth Token Group The token group to watch. Required. Webhook URL The address Localtonet calls. Required. Turn on at least one of the two webhook types and at least one of the two notification types.
-
Create #
Select Create. The webhook appears in the list below the form.
The webhook list #
Each row shows Token Webhook, Tunnel Webhook, Group Name, URL, Connected Notify and Disconnected Notify, each switch as Active or Passive. The delete button in the Action column removes the webhook after you confirm.
A webhook cannot be edited. To change its URL, group or switches, delete it and create a new one. You can create several webhooks for the same group, for example one URL for connects and another for disconnects.
The request Localtonet sends #
| Part | Value |
|---|---|
| Method | POST |
| Content type | application/json; charset=utf-8 |
| Body | A JSON object with the four fields below. |
| Field | Meaning | Values |
|---|---|---|
Id | Identifies the token or tunnel the event is about. | For Type Token: identifies the AuthToken. For Type Tunnel: the numeric ID of the tunnel, sent as a string. It is the same ID the API uses as tunnelId. |
ActionDate | When Localtonet registered the change. | Date and time in ISO 8601 format |
Type | The kind of object. | Token or Tunnel |
Status | The new state. | Connected or Disconnected |
A token event:
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}A tunnel event:
{
"Id": "<TUNNEL_ID>",
"ActionDate": "2026-01-15T10:31:12.7654321+03:00",
"Type": "Tunnel",
"Status": "Connected"
}Delivery #
- A failed call is not repeated, so your endpoint should be available and answer quickly.
- The request has no signature or secret header. To make sure a call comes from your webhook, put a long random value into the URL, for example as a path segment or query parameter, and check it in your receiver.
- A disconnect is reported when Localtonet registers that the client is gone, which can be a little later than the moment the device lost its connection.
- Parse
ActionDatewith a standard ISO 8601 parser and use the offset it carries; do not assume a fixed time zone.
Example receiver #
Any web framework works. The receiver only has to read the JSON body and answer with a success status. A minimal version with Node.js and no dependencies:
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);With this receiver, the Webhook URL is https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.
Test your webhook #
- Put one AuthToken of a test device into the token group of the webhook.
- Start the Localtonet client on that device with the token. If Send When Connected is on, your endpoint receives
TypeToken,StatusConnected. - Stop the client with Ctrl + C. Your endpoint receives
StatusDisconnected. - If Tunnel Webhook Enable is on, start and stop a tunnel of that token under My Tunnels to get the tunnel events.
No public endpoint yet? Run the receiver on your computer and publish it with a Localtonet HTTP tunnel on a different AuthToken than the one you are watching. The tunnel's request inspector then shows every webhook call; see Logs and inspection.
Troubleshooting #
"Turn on at least one webhook type." or "Turn on at least one notification type."
Switch on Token Webhook Enable or Tunnel Webhook Enable, and Send When Connected or Send When Disconnected, before you select Create.
"Group is required!"
Select a token group under Auth Token Group. If the list is empty, create a group under My Tokens and add your tokens to it.
No request arrives
Check that the AuthToken of the device is a member of the group the webhook watches, that the matching switches show Active in the list, and that the URL is reachable from the internet (not localhost or a private address). Test the URL yourself:
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"}'I get token events but no tunnel events
Tunnel Webhook must be Active for the webhook, and the tunnel must belong to an AuthToken that is in the group.