# Вихідні веб-хуки

Canonical page: https://phishdestroy.github.io/TgWitness/uk/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-запитами. Використовується семантика «принаймні один раз» : втрачене підтвердження або перезапуск можуть призвести до повторної доставки події з тим самим ідентифікатором. Передбачено вісім спроб з експоненційним відстроченням, починаючи з 15 секунд і закінчуючи однією годиною. Для успіху необхідна відповідь 2xx. Вичерпані завдання залишають видиму помилку; доставка не гарантується після закінчення повторних спроб.

Черга вміщує 1 000 відправлень. Коли вона заповнена, сканування подій журналу призупиняється і відновлюється після звільнення місця. Завершення повного експорту, яке не можна поставити в чергу, спричиняє появу видимої помилки черги. За один прохід обробки повідомлень здійснюється до п’яти спроб доставки, а останні 100 записів про спроби зберігаються. Видалення адресата також призводить до видалення його очікуючих на доставку повідомлень.

## Приклад n8n

Імпортуйте [приклад робочого процесу](https://github.com/phishdestroy/TgWitness/blob/main/integrations/n8n-tgwitness.json). Він неактивний і не містить жодних секретних даних чи подальших дій. Встановіть `TGWITNESS_WEBHOOK_SECRET` у середовищі n8n worker, надайте цьому середовищу доступ та дозвольте використання вбудованої функції `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 не додає вхідних команд.