Вебхуки
На цій сторінці 9 розділів
Вебхук змушує Localtonet викликати вашу URL-адресу, коли пристрій (AuthToken) або тунель підключається чи відключається. Використовуйте його, щоб сповіщати команду, перезапускати сервіс або підтримувати актуальною власну сторінку статусу.
Як це працює #
- Вебхук належить до групи токенів. Він стежить за AuthToken у цій групі, за тунелями цих токенів або за тим і другим, залежно від вашого вибору.
- Коли стан відстежуваного токена чи тунелю змінюється на «підключено» або «відключено», Localtonet надсилає на вашу URL-адресу HTTP-запит
POSTз невеликим тілом JSON. - Ви обираєте, які з двох подій вам потрібні: підключення, відключення або обидві.
Перш ніж почати #
- Група токенів, що містить AuthToken, за якими ви хочете стежити. Створюйте групи в розділі Мої токени; дивіться AuthToken.
- Кінцева точка HTTP або HTTPS, доступна з інтернету, що приймає запит
POSTз тілом JSON. - Ваша власна панель керування облікового запису. Пункт меню Вебхуки не показується, поки ви працюєте в панелі керування команди.
Створіть вебхук #
-
Відкрийте «Вебхуки» #
Відкрийте Вебхуки в меню панелі керування.
-
Оберіть, про що вас сповіщати #
Налаштування Що робить Увімкнути вебхук токена Надсилає запит, коли AuthToken групи підключається або відключається, тобто коли клієнт Localtonet на цьому пристрої з’являється в мережі або виходить з неї. Увімкнути вебхук тунелю Надсилає запит, коли тунель, що належить AuthToken групи, підключається або відключається. Надсилати при підключенні Надсилає запит про перехід у стан «підключено». Надсилати при відключенні Надсилає запит про перехід у стан «відключено». Група 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. Якщо список порожній, створіть групу в розділі Мої токени і додайте до неї свої токени.
Запит не надходить
Перевірте, що 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, що входить до групи.