# Исходящие веб-хуки

Canonical page: https://phishdestroy.github.io/TgWitness/ru/docs/reference/webhooks/

Отправка событий в заданном диапазоне на HTTPS-приемники с HMAC-подписями, повторными попытками и статусом доставки.

**Текущая версия:** используйте репозиторий исходного кода; в портативной предварительной версии 0.7.0 эта функция ещё не реализована.

[Руководство по рабочему процессу](https://phishdestroy.github.io/TgWitness/docs/archive/) · [Вики](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md)

Откройте раздел **«Интеграции» → «Исходящие веб-хуки»** в выбранном рабочем пространстве. Добавьте HTTPS- приемник, выберите события «коллектор», «медиа» и «экспорт», а также, по желанию, укажите чаты для отслеживания новых сообщений и изменений. По умолчанию текст сообщений не передается. Включение выдержек добавляет не более 1 000 символов к событиям об изменении сообщений; исходные поля Telegram и учетные данные никогда не отправляются.

Один раз скопируйте секретный ключ HMAC в защищённую конфигурацию получателя. Он зашифрован в хранилище TgWitness и не может быть извлечён из панели управления. Удалите и заново создайте пункт назначения, чтобы произвести его ротацию. **Отправьте**в**синтетические тестовые** очереди тестовое сообщение без содержимого чата; обновите статус доставки, чтобы увидеть результат.

Доставка расширяет существующий цикл уведомлений наряду с Apprise. Она использует внешний маршрут рабочей среды и существующие ограничения на частные адреса назначения. Прямого резервного варианта или последующего перенаправления нет. URL-адреса не должны содержать учетные данные, строки запроса или фрагменты; для частных адресов требуется сетевое согласие на уровне сервера, а не настройка, которую пользователь панели может обойти.

## Полезная нагрузка и подпись

Схема: [`tgwitness.webhook/1`](https://github.com/phishdestroy/TgWitness/blob/main/integrations/webhook.schema.json). Каждый полезный груз содержит `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

Импортируйте [пример рабочего процесса](https://github.com/phishdestroy/TgWitness/blob/main/integrations/n8n-tgwitness.json). Он неактивен и не содержит секретных данных или последующих действий. Установите `TGWITNESS_WEBHOOK_SECRET` в среде рабочего процесса n8n, разрешите доступ к этой среде и разрешите использование встроенной функции `crypto` для узла «Code». В примере используется опция raw-body узла «Webhook», проводится проверка подписи и свежести данных, а также подтверждаются проверенные события. Это соответствует [документированной реализации](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Webhook/Webhook.node.ts) узла.

Перед добавлением записей или уведомлений в SIEM добавьте надежное хранилище с идемпотентностью, индексированное по ключу `event_id`. Ограничьте редактирование рабочих процессов n8n и хранение журналов выполнения в соответствии с данными, которые вы решили отправить. TgWitness не добавляет входящих команд.