Перейти до вмісту
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 групи, підключається або відключається.
    Надсилати при підключенніНадсилає запит про перехід у стан «підключено».
    Надсилати при відключенніНадсилає запит про перехід у стан «відключено».
    Група 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. Якщо список порожній, створіть групу в розділі Мої токени і додайте до неї свої токени.

Запит не надходить

Перевірте, що 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, що входить до групи.

Підтримка