Вебхуки
На этой странице 9 разделов
Вебхук заставляет Localtonet обращаться по вашему URL, когда устройство (AuthToken) или туннель подключается либо отключается. Используйте его, чтобы оповещать команду, перезапускать сервис или поддерживать в актуальном состоянии собственную страницу статуса.
Как это работает #
- Вебхук привязан к группе токенов. Он отслеживает AuthToken из этой группы, туннели этих токенов или и то и другое, в зависимости от вашего выбора.
- Когда состояние отслеживаемого токена или туннеля меняется на «подключён» или «отключён», Localtonet отправляет на ваш URL запрос HTTP
POSTс небольшим телом JSON. - Вы выбираете, какие из двух событий вам нужны: подключение, отключение или оба.
Перед началом #
- Группа токенов, в которую входят AuthToken, которые вы хотите отслеживать. Группы создаются в разделе Мои токены; см. AuthToken.
- Конечная точка HTTP или HTTPS, доступная из интернета и принимающая запрос
POSTс телом JSON. - Панель управления вашего личного аккаунта. Пункт меню Вебхуки не отображается, пока вы работаете в панели управления команды.
Создание вебхука #
-
Откройте «Вебхуки» #
Откройте Вебхуки в меню панели управления.
-
Выберите, о чём вас оповещать #
Настройка Что делает Вебхук токена Отправляет запрос, когда AuthToken из группы подключается или отключается, то есть когда клиент Localtonet на этом устройстве выходит в сеть или уходит из сети. Вебхук туннеля Отправляет запрос, когда туннель, принадлежащий AuthToken из группы, подключается или отключается. Отправлять при подключении Отправляет запрос при переходе в состояние «подключён». Отправлять при отключении Отправляет запрос при переходе в состояние «отключён». Группа токенов Группа токенов, которую нужно отслеживать. Обязательно. URL вебхука Адрес, по которому обращается Localtonet. Обязательно. Включите хотя бы один из двух типов вебхука и хотя бы один из двух типов уведомлений.
-
Создать #
Нажмите Создать. Вебхук появится в списке под формой.
Список вебхуков #
В каждой строке показаны Вебхук токена, Вебхук туннеля, Название группы, 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 без зависимостей:
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>.
Проверка вебхука #
- Добавьте один AuthToken тестового устройства в группу токенов вебхука.
- Запустите клиент Localtonet на этом устройстве с токеном. Если включено Отправлять при подключении, ваша конечная точка получит
TypeToken,StatusConnected. - Остановите клиент сочетанием Ctrl + C. Ваша конечная точка получит
StatusDisconnected. - Если включён Вебхук туннеля, запустите и остановите туннель этого токена в разделе «Мои туннели», чтобы получить события туннеля.
Пока нет публичной конечной точки? Запустите приёмник на своём компьютере и опубликуйте его через туннель HTTP Localtonet с другим AuthToken, а не тем, который вы отслеживаете. Тогда инспектор запросов туннеля покажет каждый вызов вебхука; см. Журналы и инспекция.
Устранение неполадок #
«Включите хотя бы один тип вебхука.» или «Включите хотя бы один тип уведомлений.»
Прежде чем нажимать Создать, включите Вебхук токена или Вебхук туннеля, а также Отправлять при подключении или Отправлять при отключении.
«Укажите группу!»
Выберите группу токенов в поле Группа токенов. Если список пуст, создайте группу в разделе Мои токены и добавьте в неё свои токены.
Запрос не приходит
Проверьте, что AuthToken устройства входит в группу, которую отслеживает вебхук, что нужные переключатели в списке показаны как Активен и что URL доступен из интернета (не localhost и не частный адрес). Проверьте 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"}'Я получаю события токена, но не получаю события туннеля
Для вебхука Вебхук туннеля должен быть Активен, а туннель должен принадлежать AuthToken, входящему в группу.