Webhooks
En esta página 9 secciones
Un webhook hace que Localtonet llame a una URL tuya cuando un dispositivo (AuthToken) o un túnel se conecta o se desconecta. Úsalo para avisar a tu equipo, reiniciar un servicio o mantener actualizada tu propia página de estado.
Cómo funciona #
- Un webhook pertenece a un grupo de tokens. Vigila los AuthToken de ese grupo, los túneles de esos tokens, o ambos, según elijas.
- Cuando el estado de un token o de un túnel vigilado cambia a conectado o desconectado, Localtonet envía a tu URL una solicitud HTTP
POSTcon un cuerpo JSON pequeño. - Tú eliges cuál de los dos eventos quieres: conectado, desconectado o ambos.
Antes de empezar #
- Un grupo de tokens que contenga los AuthToken que quieres vigilar. Crea grupos en Mis tokens; consulta AuthTokens.
- Un endpoint HTTP o HTTPS accesible desde internet que acepte una solicitud
POSTcon un cuerpo JSON. - El dashboard de tu propia cuenta. El elemento de menú Webhooks no se muestra mientras trabajas en el dashboard de un equipo.
Crea un webhook #
-
Abre Webhooks #
Abre Webhooks en el menú del dashboard.
-
Elige de qué quieres que te avisen #
Ajuste Qué hace Activar webhook de token Envía una solicitud cuando un AuthToken del grupo se conecta o se desconecta, es decir, cuando el cliente de Localtonet de ese dispositivo se pone en línea o se queda sin conexión. Activar webhook de túnel Envía una solicitud cuando un túnel que pertenece a un AuthToken del grupo se conecta o se desconecta. Enviar al conectarse Envía la solicitud para el cambio a conectado. Enviar al desconectarse Envía la solicitud para el cambio a desconectado. Grupo de AuthToken El grupo de tokens que se vigila. Obligatorio. URL del webhook La dirección a la que llama Localtonet. Obligatoria. Activa al menos uno de los dos tipos de webhook y al menos uno de los dos tipos de notificación.
-
Crear #
Selecciona Crear. El webhook aparece en la lista debajo del formulario.
La lista de webhooks #
Cada fila muestra Webhook de token, Webhook de túnel, Nombre del grupo, URL, Aviso de conexión y Aviso de desconexión, y cada interruptor aparece como Activo o Inactivo. El botón de eliminar de la columna Acción quita el webhook después de que lo confirmes.
Un webhook no se puede editar. Para cambiar su URL, su grupo o sus interruptores, elimínalo y crea uno nuevo. Puedes crear varios webhooks para el mismo grupo, por ejemplo una URL para las conexiones y otra para las desconexiones.
La solicitud que envía Localtonet #
| Elemento | Valor |
|---|---|
| Método | POST |
| Tipo de contenido | application/json; charset=utf-8 |
| Cuerpo | Un objeto JSON con los cuatro campos siguientes. |
| Campo | Significado | Valores |
|---|---|---|
Id | Identifica el token o el túnel al que se refiere el evento. | Para Type Token: identifica el AuthToken. Para Type Tunnel: el ID numérico del túnel, enviado como cadena. Es el mismo ID que la API usa como tunnelId. |
ActionDate | Cuándo registró Localtonet el cambio. | Fecha y hora en formato ISO 8601 |
Type | El tipo de objeto. | Token o Tunnel |
Status | El nuevo estado. | Connected o Disconnected |
Un evento de token:
{
"Id": "<YOUR_TOKEN>",
"ActionDate": "2026-01-15T10:30:00.1234567+03:00",
"Type": "Token",
"Status": "Disconnected"
}Un evento de túnel:
{
"Id": "<TUNNEL_ID>",
"ActionDate": "2026-01-15T10:31:12.7654321+03:00",
"Type": "Tunnel",
"Status": "Connected"
}Entrega #
- Una llamada fallida no se repite, así que tu endpoint debe estar disponible y responder rápido.
- La solicitud no lleva firma ni cabecera secreta. Para asegurarte de que una llamada procede de tu webhook, pon un valor aleatorio largo en la URL, por ejemplo como segmento de ruta o parámetro de consulta, y compruébalo en tu receptor.
- Una desconexión se notifica cuando Localtonet registra que el cliente ya no está, lo cual puede ocurrir algo después del momento en que el dispositivo perdió la conexión.
- Interpreta
ActionDatecon un analizador estándar de ISO 8601 y usa el desfase que incluye; no supongas una zona horaria fija.
Receptor de ejemplo #
Sirve cualquier framework web. El receptor solo tiene que leer el cuerpo JSON y responder con un estado de éxito. Una versión mínima con Node.js y sin dependencias:
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 este receptor, la URL del webhook es https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.
Prueba tu webhook #
- Pon un AuthToken de un dispositivo de prueba en el grupo de tokens del webhook.
- Inicia el cliente de Localtonet en ese dispositivo con el token. Si Enviar al conectarse está activado, tu endpoint recibe
TypeToken,StatusConnected. - Detén el cliente con Ctrl + C. Tu endpoint recibe
StatusDisconnected. - Si Activar webhook de túnel está activado, inicia y detén un túnel de ese token en Mis túneles para recibir los eventos de túnel.
¿Todavía no tienes un endpoint público? Ejecuta el receptor en tu ordenador y publícalo con un túnel HTTP de Localtonet con un AuthToken distinto del que estás vigilando. El inspector de solicitudes del túnel muestra entonces cada llamada del webhook; consulta Registros e inspección.
Solución de problemas #
"Activa al menos un tipo de webhook." o "Activa al menos un tipo de notificación."
Activa Activar webhook de token o Activar webhook de túnel, y Enviar al conectarse o Enviar al desconectarse, antes de seleccionar Crear.
"¡El grupo es obligatorio!"
Selecciona un grupo de tokens en Grupo de AuthToken. Si la lista está vacía, crea un grupo en Mis tokens y añade tus tokens.
No llega ninguna solicitud
Comprueba que el AuthToken del dispositivo es miembro del grupo que vigila el webhook, que los interruptores correspondientes muestran Activo en la lista y que la URL es accesible desde internet (no localhost ni una dirección privada). Prueba tú mismo la 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"}'Recibo eventos de token pero no de túnel
Webhook de túnel debe estar Activo en el webhook, y el túnel debe pertenecer a un AuthToken que esté en el grupo.