Saltar al contenido
Localtonet Localtonet Panel

Webhooks

Ayuda con esta página
En esta página 9 secciones
  1. Cómo funciona
  2. Antes de empezar
  3. Crea un webhook
  4. Abre Webhooks
  5. Elige de qué quieres que te avisen
  6. Crear
  7. La lista de webhooks
  8. La solicitud que envía Localtonet
  9. Entrega
  10. Receptor de ejemplo
  11. Prueba tu webhook
  12. Solución de problemas
  13. Páginas relacionadas

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 POST con 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 POST con 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 #

  1. Abre Webhooks #

    Abre Webhooks en el menú del dashboard.

  2. Elige de qué quieres que te avisen #

    AjusteQué hace
    Activar webhook de tokenEnví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únelEnvía una solicitud cuando un túnel que pertenece a un AuthToken del grupo se conecta o se desconecta.
    Enviar al conectarseEnvía la solicitud para el cambio a conectado.
    Enviar al desconectarseEnvía la solicitud para el cambio a desconectado.
    Grupo de AuthTokenEl grupo de tokens que se vigila. Obligatorio.
    URL del webhookLa 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.

  3. 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 #

ElementoValor
MétodoPOST
Tipo de contenidoapplication/json; charset=utf-8
CuerpoUn objeto JSON con los cuatro campos siguientes.
CampoSignificadoValores
IdIdentifica 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.
ActionDateCuándo registró Localtonet el cambio.Fecha y hora en formato ISO 8601
TypeEl tipo de objeto.Token o Tunnel
StatusEl nuevo estado.Connected o Disconnected

Un evento de token:

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

Un evento de túnel:

Cuerpo de la solicitud
{
  "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 ActionDate con 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:

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

Con este receptor, la URL del webhook es https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.

Prueba tu webhook #

  1. Pon un AuthToken de un dispositivo de prueba en el grupo de tokens del webhook.
  2. Inicia el cliente de Localtonet en ese dispositivo con el token. Si Enviar al conectarse está activado, tu endpoint recibe Type Token, Status Connected.
  3. Detén el cliente con Ctrl + C. Tu endpoint recibe Status Disconnected.
  4. 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:

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"}'
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.

Soporte