Вебхуки и события
Панель создаёт событие всякий раз, когда происходит что-то важное: у клиента заканчивается трафик, узел отключился, вход с нового адреса, резервная копия не удалась. Подписчик вебхука — это ваш адрес, который получает запрошенные им события в виде подписанных HTTPS-запросов. Здесь описано, как добавлять подписчиков, проверять, что до них дошло, и задавать пороги оповещений. Страница находится в Сервисы → Вебхуки.
Чаты Telegram и адреса почты получают те же события через свои страницы: см. Telegram и Почта. Все события и их поля перечислены в Каталог событий; как устроена шина событий, описано в Шина событий.
Добавление подписчика
- Добавить.
- Название: что это за получатель.
- URL: куда панель отправляет каждое событие методом
POST. - События: оставьте Все события, чтобы получать каждое событие, включая те, что добавит следующий выпуск, или снимите отметку и выберите сами.
- Только события о: оставьте Все или выберите один аккаунт, чтобы получать только касающиеся его события: о пользователях реселлера, о его собственных входах.
- Принадлежит: оставьте Без дополнения (ручной вебхук), если только получатель не ваше собственное дополнение, работающее рядом с панелью (см. ниже).
- Сохранить.
После этого панель один раз показывает Секрет подписи. Передайте его получателю: по нему тот проверяет, что запрос пришёл от вашей панели.
Отправить тестовое событие в строке сразу отправляет этому подписчику panel.ping и показывает ответ получателя.
Какие адреса разрешены
Введённый здесь URL не может указывать на сам хост панели или её частную сеть: loopback, частные диапазоны, link-local и подобные адреса отклоняются при подключении панели. Так вебхук нельзя использовать, чтобы дотянуться до сервисов, которые должны оставаться внутри.
Вебхук, принадлежащий токену дополнения (Принадлежит), может обращаться к этому хосту и его частной сети, например к сети Docker, потому что именно там работает дополнение рядом с панелью. Link-local и адреса метаданных для него тоже закрыты. Принадлежит потом изменить нельзя. Подписанное дополнение регистрирует свой вебхук само; см. Страница дополнений.
Как выглядит доставка
Каждое событие — это POST с телом в JSON:
{
"v": 1,
"id": 4182,
"event": "node.disconnected",
"time": 1760180000,
"data": { "nodeId": 3, "name": "de-1", "status": "error", "message": "connection refused" }
}и такими заголовками:
| Заголовок | Содержит |
|---|---|
X-Nexora-Event | имя события, как в теле |
X-Nexora-Delivery | идентификатор этой доставки; одинаковый при каждом повторе |
X-Nexora-Signature | t=<unix seconds>,v1=<hex> |
Значение v1 — это HMAC-SHA256(secret, "<t>.<body>"): отметка времени, точка, затем сырое тело ровно в том виде, в каком получено. Получатель вычисляет то же значение своим секретом, сравнивает их за постоянное время и отклоняет запрос, чей t отличается от его часов больше чем на пять минут. Полный конверт и разобранный пример есть в Каталог событий.
Ответ 2xx означает доставку. Всё остальное, включая перенаправление, или отсутствие ответа в течение десяти секунд — неудача. Перенаправления не выполняются.
Содержимое событий минимально: идентификаторы, имена и числа, никогда не пароль, ключ или ссылка подписки. Получатель, которому нужно больше, читает это из API с токеном (см. Токены API).
Повторы и серия неудач
Неудачная доставка повторяется через 30 секунд, затем каждый раз через вдвое больший интервал, но не реже раза в час, с небольшим случайным разбросом, чтобы вернувшегося получателя не накрыли все повторы сразу. После десяти попыток доставка прекращается со статусом Прекращено. Это примерно три часа.
Доставки одному подписчику идут по одной и по порядку, поэтому получатель видит user.disabled раньше последовавшего за ним user.enabled.
Подписчик, который постоянно отвечает неудачей, выключается сам, но только когда верно и то, и другое: пятьдесят неудач подряд и первая из них больше суток назад. Получатель, который лежал час, не выключается и получает накопленное, когда вернётся. Выключенный подписчик показывает, сколько попыток не удалось. Почините получателя, затем снова включите подписчика — счётчик начнётся заново.
Каждая прекращённая доставка учитывается в метриках панели, поэтому оповещение о ней можно настроить снаружи: см. Мониторинг и метрики.
Журнал доставок
Доставки в строке показывают, что было отправлено этому подписчику: событие, время, номер попытки, код ответа получателя, ошибку и статус (Ожидает, Доставлено или Прекращено), а для ожидающей доставки — время следующей попытки.
Отправить снова у любой доставки ставит её в очередь ещё раз с новым счётчиком попыток. Её идентификатор X-Nexora-Delivery сохраняется, поэтому получатель, который игнорирует уже виденные идентификаторы, проигнорирует и её.
По умолчанию журнал хранит семь дней. Это меняет настройка event_retention_days (до 90) через nexora-panel config set (см. Командная строка).
Смена секрета
Сменить секрет в строке создаёт новый секрет подписи и показывает его один раз. Сначала обновите получателя: старый секрет перестаёт работать со следующей доставкой.
Подписчик с отметкой Без подписи перенесён из единственного адреса вебхука, который был у старых панелей, и не имеет секрета, поэтому его доставки не подписываются. Создайте ему секрет и передайте его получателю.
Оповещения о хостах
Карточка Оповещения о хосте задаёт, когда панель создаёт оповещения об узлах:
| Поле | По умолчанию | Создаёт |
|---|---|---|
| Заполнение диска | 90 % | node.disk_high, когда корневая файловая система узла превышает порог, и node.disk_recovered, когда она опускается на пять пунктов ниже |
| Использование памяти | 90 % | node.memory_high и node.memory_recovered так же |
| Отклонённых соединений в час | 100 | node.rejections_high, когда один узел за скользящий час отклоняет через один блокирующий аутбаунд больше соединений, чем задано |
Диск и память считываются с каждого подключённого узла раз в пять минут. Число отклонений сообщает сам узел при каждом heartbeat: он считает соединения, отклонённые через блокирующий аутбаунд, например block-torrent из пресета против торрентов (см. Маршрутизация и DNS). Каждое оповещение создаётся один раз на каждое пересечение порога, а не на каждое измерение или соединение. 0 выключает это оповещение.
Предупреждения по аккаунтам
Карточка Предупреждения по аккаунтам задаёт два предупреждения об аккаунтах, которые ещё работают:
| Поле | По умолчанию | Создаёт |
|---|---|---|
| Израсходовано трафика | 80 % | user.quota_warning, когда аккаунт израсходовал эту долю своего трафика |
| Дней до истечения | 7,1 | user.expiring, когда до даты окончания аккаунта остаётся одно из этих значений |
Несколько значений разделяются запятыми; отправляется самое срочное из пройденных. Каждое предупреждение звучит один раз и снова взводится само: продление, дополнительный трафик или сброс расхода запускают отсчёт заново. 0 выключает это предупреждение.
Вебхуки дополнений
Вебхук, который принадлежит дополнению, показан с меткой Дополнение: имя. Здесь его нельзя изменить или удалить; управляйте им вместе с дополнением на странице Страница дополнений. Включить его снова здесь можно, если его выключила серия неудач.
См. также
- Каталог событий: все события, их поля и кто может их читать.
- Шина событий: как работает шина событий.
- Telegram и Почта: те же события для людей.
- Токены API: прочитать больше, чем несёт событие.