Справочник / Архив и интеграции
Вебхуки TgWitness: HMAC-подпись и доставка событий
Отправка событий в заданном диапазоне на HTTPS-приемники с HMAC-подписями, повторными попытками и статусом доставки.
TgWitness / Документация · Интеграция с архивами
Руководство по рабочему процессу · Вики
Откройте Дополнительные инструменты → Интеграции → Исходящие веб-хуки в выбранной рабочей области. Добавьте HTTPS- приемник, выберите события коллектор/медиа/экспорт и, при желании, выберите чаты для новых наблюдений и изменений. По умолчанию текст сообщений отключен. Включение выдержек добавляет не более 1,000 символов к событиям изменения сообщений; необработанные поля Telegram и учетные данные никогда не отправляются.
Один раз скопируйте секретный ключ HMAC в защищённую конфигурацию получателя. Он зашифрован в хранилище TgWitness и не может быть извлечён из панели управления. Удалите и заново создайте пункт назначения, чтобы произвести его ротацию. Отправьте в синтетические тестовые очереди тестовое сообщение без содержимого чата; обновите статус доставки, чтобы увидеть результат.
Доставка расширяет существующий цикл уведомлений наряду с Apprise. Она использует внешний маршрут рабочей среды и существующие ограничения на частные адреса назначения. Прямого резервного варианта или последующего перенаправления нет. URL-адреса не должны содержать учетные данные, строки запроса или фрагменты; для частных адресов требуется сетевое согласие на уровне сервера, а не настройка, которую пользователь панели может обойти.
Полезная нагрузка и подпись#
Схема: tgwitness.webhook/1. Каждый полезный груз
содержит event_id, timestamp, workspace, type, synthetic и счетчики.
События, записываемые в журнал, включают свою последовательность и хеш. Завершение полного экспорта и
синтетические тесты являются событиями доставки, без вымышленной ссылки на подписанный журнал.
Уведомления об удалении в Telegram и missing_on_recheck остаются отдельными типами.
Заголовок X-TgWitness-Signature — t=UNIX_SECONDS,v1=HEX_HMAC_SHA256.
Вычислите HMAC над точными байтами timestamp + "." + raw_request_body, используя
отображаемый секрет в виде байтов UTF-8. Сравнивайте подписи за постоянное время до
разбора или обработки тела сообщения. Отклоняйте временные метки, отличающиеся более чем на пять минут от
вашего времени. Временная метка обновляется при каждой попытке доставки.
Используйте event_id в качестве ключа идемпотентности в долговечном хранилище с атомарным уникальным
ограничением до возникновения побочных эффектов. Один только действительный подпись не предотвращает
повторное воспроизведение недавнего запроса. Храните обработанные идентификаторы как минимум в течение всего
окна повторных попыток; храните их дольше, если получатель может повторно обработать сохраненные события.
Повторные попытки#
Доставки надежно ставятся в очередь перед HTTP-запросами. Они используют семантику по крайней мере один раз : потерянное подтверждение или перезапуск могут привести к повторной доставке события с тем же ID. Предусмотрено восемь попыток с экспоненциальным откатом, начиная с 15 секунд и заканчивая одним часом. Для успеха требуется ответ с кодом 2xx. Задание, исчерпавшее количество попыток, остается видимым с указанием ошибки для проверки.
Очередь вмещает 1 000 отправлений. Когда она заполняется, сканирование событий журнала приостанавливается и возобновляется после появления свободного места. Завершение полного экспорта, которое не может быть поставлено в очередь, вызывает отображение ошибки в очереди. За один проход уведомлений предпринимается до пяти попыток доставки, а последние 100 записей о попытках сохраняются. Удаление адресата также приводит к удалению его ожидающих доставок.
Пример n8n#
Импортируйте пример рабочего процесса. Он неактивен
и не содержит секретных данных или последующих действий. Установите TGWITNESS_WEBHOOK_SECRET в
среде рабочего процесса n8n, разрешите доступ к этой среде и разрешите использование встроенной функции crypto
для узла «Code». В примере используется опция raw-body узла «Webhook»,
проводится проверка подписи и свежести данных, а также подтверждаются проверенные события. Это соответствует
документированной реализации узла.
Перед добавлением записей или уведомлений в SIEM добавьте надежное хранилище с идемпотентностью,
индексированное по ключу event_id. Ограничьте редактирование рабочих процессов n8n и хранение журналов выполнения
в соответствии с данными, которые вы решили отправить. TgWitness не добавляет входящих команд.