Перейти к содержимому
Localtonet Localtonet Панель управления

Вебхуки

Помощь по этой странице
На этой странице 9 разделов
  1. Как это работает
  2. Перед началом
  3. Создание вебхука
  4. Откройте «Вебхуки»
  5. Выберите, о чём вас оповещать
  6. Создать
  7. Список вебхуков
  8. Запрос, который отправляет Localtonet
  9. Доставка
  10. Пример приёмника
  11. Проверка вебхука
  12. Устранение неполадок
  13. Связанные страницы

Вебхук заставляет Localtonet обращаться по вашему URL, когда устройство (AuthToken) или туннель подключается либо отключается. Используйте его, чтобы оповещать команду, перезапускать сервис или поддерживать в актуальном состоянии собственную страницу статуса.

Как это работает #

  • Вебхук привязан к группе токенов. Он отслеживает AuthToken из этой группы, туннели этих токенов или и то и другое, в зависимости от вашего выбора.
  • Когда состояние отслеживаемого токена или туннеля меняется на «подключён» или «отключён», Localtonet отправляет на ваш URL запрос HTTP POST с небольшим телом JSON.
  • Вы выбираете, какие из двух событий вам нужны: подключение, отключение или оба.

Перед началом #

  • Группа токенов, в которую входят AuthToken, которые вы хотите отслеживать. Группы создаются в разделе Мои токены; см. AuthToken.
  • Конечная точка HTTP или HTTPS, доступная из интернета и принимающая запрос POST с телом JSON.
  • Панель управления вашего личного аккаунта. Пункт меню Вебхуки не отображается, пока вы работаете в панели управления команды.

Создание вебхука #

  1. Откройте «Вебхуки» #

    Откройте Вебхуки в меню панели управления.

  2. Выберите, о чём вас оповещать #

    НастройкаЧто делает
    Вебхук токенаОтправляет запрос, когда AuthToken из группы подключается или отключается, то есть когда клиент Localtonet на этом устройстве выходит в сеть или уходит из сети.
    Вебхук туннеляОтправляет запрос, когда туннель, принадлежащий AuthToken из группы, подключается или отключается.
    Отправлять при подключенииОтправляет запрос при переходе в состояние «подключён».
    Отправлять при отключенииОтправляет запрос при переходе в состояние «отключён».
    Группа токеновГруппа токенов, которую нужно отслеживать. Обязательно.
    URL вебхукаАдрес, по которому обращается Localtonet. Обязательно.

    Включите хотя бы один из двух типов вебхука и хотя бы один из двух типов уведомлений.

  3. Создать #

    Нажмите Создать. Вебхук появится в списке под формой.

Список вебхуков #

В каждой строке показаны Вебхук токена, Вебхук туннеля, Название группы, URL, При подключении и При отключении, а каждый переключатель отображается как Активен или Неактивен. Кнопка удаления в столбце Действие удаляет вебхук после подтверждения.

Вебхук нельзя изменить. Чтобы сменить его URL, группу или переключатели, удалите его и создайте новый. Для одной и той же группы можно создать несколько вебхуков, например один URL для подключений и другой для отключений.

Запрос, который отправляет Localtonet #

ЧастьЗначение
МетодPOST
Тип содержимогоapplication/json; charset=utf-8
ТелоОбъект JSON с четырьмя полями, описанными ниже.
ПолеЗначениеВозможные значения
IdОпределяет токен или туннель, о котором событие.Для Type Token: определяет AuthToken. Для Type Tunnel: числовой ID туннеля, передаваемый как строка. Это тот же ID, который API использует как tunnelId.
ActionDateКогда Localtonet зарегистрировал изменение.Дата и время в формате ISO 8601
TypeВид объекта.Token или Tunnel
StatusНовое состояние.Connected или Disconnected

Событие токена:

Тело запроса
{
  "Id": "<YOUR_TOKEN>",
  "ActionDate": "2026-01-15T10:30:00.1234567+03:00",
  "Type": "Token",
  "Status": "Disconnected"
}

Событие туннеля:

Тело запроса
{
  "Id": "<TUNNEL_ID>",
  "ActionDate": "2026-01-15T10:31:12.7654321+03:00",
  "Type": "Tunnel",
  "Status": "Connected"
}

Доставка #

  • Неудавшийся вызов не повторяется, поэтому ваша конечная точка должна быть доступна и быстро отвечать.
  • В запросе нет подписи или секретного заголовка. Чтобы убедиться, что вызов исходит от вашего вебхука, поместите в URL длинное случайное значение, например как сегмент пути или параметр запроса, и проверяйте его в своём приёмнике.
  • Об отключении сообщается, когда Localtonet регистрирует, что клиента больше нет; это может произойти чуть позже, чем устройство потеряло соединение.
  • Разбирайте ActionDate стандартным парсером ISO 8601 и используйте содержащееся в нём смещение; не предполагайте фиксированный часовой пояс.

Пример приёмника #

Подойдёт любой веб-фреймворк. Приёмнику нужно лишь прочитать тело JSON и ответить статусом успеха. Минимальная версия на Node.js без зависимостей:

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

С этим приёмником URL вебхука выглядит так: https://<YOUR_HOST>/localtonet/<YOUR_SECRET>.

Проверка вебхука #

  1. Добавьте один AuthToken тестового устройства в группу токенов вебхука.
  2. Запустите клиент Localtonet на этом устройстве с токеном. Если включено Отправлять при подключении, ваша конечная точка получит Type Token, Status Connected.
  3. Остановите клиент сочетанием Ctrl + C. Ваша конечная точка получит Status Disconnected.
  4. Если включён Вебхук туннеля, запустите и остановите туннель этого токена в разделе «Мои туннели», чтобы получить события туннеля.

Пока нет публичной конечной точки? Запустите приёмник на своём компьютере и опубликуйте его через туннель HTTP Localtonet с другим AuthToken, а не тем, который вы отслеживаете. Тогда инспектор запросов туннеля покажет каждый вызов вебхука; см. Журналы и инспекция.

Устранение неполадок #

«Включите хотя бы один тип вебхука.» или «Включите хотя бы один тип уведомлений.»

Прежде чем нажимать Создать, включите Вебхук токена или Вебхук туннеля, а также Отправлять при подключении или Отправлять при отключении.

«Укажите группу!»

Выберите группу токенов в поле Группа токенов. Если список пуст, создайте группу в разделе Мои токены и добавьте в неё свои токены.

Запрос не приходит

Проверьте, что AuthToken устройства входит в группу, которую отслеживает вебхук, что нужные переключатели в списке показаны как Активен и что URL доступен из интернета (не localhost и не частный адрес). Проверьте 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"}'
Я получаю события токена, но не получаю события туннеля

Для вебхука Вебхук туннеля должен быть Активен, а туннель должен принадлежать AuthToken, входящему в группу.

Поддержка