Вебхук і секрет у .env: форма стукає до твого сервера

Що ти сьогодні збереш

Модуль I · IT Skills (Cloud Services & Cyber Security) · тема 2, урок 1 з 2 · 120 хвилин

Досі твій сайт лише віддавав сторінки. Сьогодні він уперше почне приймати дані. Від Google, автоматично, щойно хтось надішле анкету. Це і є вебхук.

Ти збереш ланцюг із п’яти ланок. Дані з чужої форми самі приїжджатимуть у твій файл. І перший у житті секрет ляже так, як його кладуть дорослі.

Після уроку ти вмієш

• робити на своєму сайті адресу, куди чужий сервіс сам надсилає дані;
• відповідати на запит потрібним кодом: 200, 401, 403, 405;
• ховати пароль до цієї адреси у файл, який не побачить браузер;
• складати анкети у файл поза теками сайту, рядок за рядком;
• знаходити у власному коді рядки, які не можна нікуди віддавати.

Слова «вебхук», «токен», .env і «JSONL» поки нічого не означають — розберемо їх по черзі.

Хід уроку

У кінці уроку в тебе працює:

• Google-форма (щонайменше 4 поля) з прив’язаною таблицею;
• Apps Script, який сам шле HTTPS POST на твою адресу після кожного надсилання;
• ~/www/api/inbox.php — приймач, який перевіряє токен і коди відповіді;
• ~/.env із правами 600 — там і тільки там лежить токен;
• ~/data/leads.jsonl — журнал анкет поза веб-корінням.

Що куди їде

Вебхук: не ти питаєш, а до тебе стукають

Одна зміна напрямку — і зникає ціла категорія роботи

Є два способи дізнатися, що прийшла нова анкета.

Опитування (polling). Твоя програма щохвилини питає Google: «є щось нове?» У 99 випадках зі 100 відповідь — «ні». Ти витрачаєш запити, трафік і ліміти. А новина все одно приходить із запізненням до хвилини.

Вебхук (webhook). Ти один раз кажеш Google свою адресу. Далі мовчиш. Хтось надсилає форму — і Google сам стукає на цю адресу. Дані він приносить у тілі запиту. Нуль зайвих запитів, затримка — секунди.

Чому вебхуку потрібна публічна адреса

Стукати можна лише в двері, які видно з вулиці. Твій ноутбук сидить за домашнім роутером. З інтернету його не знайти: адреси, за якою можна прийти, у нього просто немає. Тому в тебе є сабдомен 91.219.61.4/s/<логін>. Це і є твої двері.

Три вимоги до адреси, яку ти віддаєш чужому сервісу:

• вона доступна ззовні — не localhost і не 192.168.x.x;
• вона працює по HTTPS — токен їде в заголовку, і його не можна віддавати відкритим текстом;
• вона відповідає швидко — Apps Script не чекатиме хвилину.

Увесь ланцюг однією схемою

Із чого складається запит, який до тебе прилетить

Метод, шлях, заголовки, порожній рядок, тіло. Чотири частини — і кожна щось означає

HTTP-запит — це звичайний текст, який їде по мережі. Відкриваєш сторінку — браузер шле GET: «дай мені це». Apps Script надсилає анкету — він шле POST: «на, візьми це й зроби щось».

Чому токен їде в заголовку, а не в тілі й не в адресі

Коди відповіді: що твій сервер каже тому, хто стукає

Код — це не «помилка». Це коротка інструкція, що робити далі

Той, хто до тебе стукає, — програма. Вона не читає українською. Єдине, що вона розуміє, — тризначне число у відповіді. Від нього залежить, повторить вона запит чи назавжди його викине.

Ще один код побачиш майже одразу: 405 Method Not Allowed. Він прилетить, щойно ти відкриєш /api/inbox.php у браузері. Браузер шле GET, а твій приймач бере лише POST.

Дерево рішень твого обробника

Інспектор запиту

Склади запит — і подивись, на якому саме кроці він помре

Нижче — модель твого обробника. Обираєш, що покласти в запит, і тиснеш «Надіслати». Далі покроково видно, як приймач його перевіряє. Який код повернеться. Що потрапить у лог. І чи додасться рядок у leads.jsonl.

Інспектор — модель, а не справжня мережа: він показує ту саму послідовність перевірок, що й код inbox.php нижче. Числа в рядку логу (IP, довжина, час) — ілюстративні.

Навіщо взагалі токен

Твоя адреса — не таємниця. Таємниця — ключ до неї

Типове заперечення: «адресу знаю тільки я, навіщо перевірка?» Адресу знаєш не тільки ти. Публічні адреси знаходять автоматично. За списками виданих сертифікатів HTTPS. За чужими логами й посиланнями. Просто перебором типових шляхів: /api/, /webhook.php, /inbox.php. Це роблять цілодобово й не проти тебе особисто — сканують усе підряд.

Що буває з ендпойнтом без перевірки:

• у leads.jsonl лягають тисячі порожніх або рекламних записів, і справжню анкету ти вже не знайдеш;
• файл росте, поки не впреться в дискову квоту — і тоді перестають записуватися вже справжні дані;
• чужі люди підкидають тобі дані, які потім показує твоя сторінка.

Найпростіший захист — спільний секрет (shared secret). Обидві сторони знають один рядок. Той, хто стукає, кладе його в заголовок. Це не криптографія й не підпис. Хтось підгляне цей рядок — і стукатиме замість тебе. Тому це перший рівень, а не останній. Справжній підпис HMAC з міткою часу ти зробиш на уроці 12.

Як народжується токен

Токен має бути випадковим і довгим. Не «myschool2026», не дата народження, не назва класу. Генерує його машина:

-hex 24 — це 24 випадкові байти, записані як 48 шістнадцяткових символів. Підібрати такий рядок перебором неможливо. Варіантів 2 у степені 192 — число з 58 цифр.

Секрет у .env: чому не в коді

Три різні шляхи, якими код витікає — і жоден із них не про злам

Написати $token = "a7f3c9e2…"; просто в inbox.php здається безпечним: цей файл же на сервері. Проблема в тому, що код не лишається на сервері.

Шлях перший: код читають люди

Ти покажеш файл однокласнику, попросиш допомоги в чаті, скинеш скрін учителю, вставиш у AI-редактор. Токен їде разом із кодом у кожну копію. І жодну з цих копій ти вже не контролюєш.

Шлях другий: код потрапляє в git

Комміт — це запис назавжди. Ти видалиш рядок наступним коммітом, а старий лишиться в історії. Команда git log -p покаже його будь-кому, хто має репозиторій. На GitHub такі рядки знаходять автоматично. Секрет, залитий у публічний репозиторій, зазвичай починають використовувати за хвилини, а не за дні.

Шлях третій: код віддається браузером

Це найгірший випадок. Частина файлів у ~/www/ сервером не виконується: .js, .json, .txt, .env, .bak. Такий файл віддають кожному, хто попросить. Ламати нічого не треба — досить знати ім’я.

Права 600: що це насправді означає

На сервері живуть три класи, разом 63 учні. Файл із правами 644 (-rw-r--r--) читає будь-хто з них однією командою cat. Для секрету потрібне 600.

Два нижні рядки — це блокуючий критерій env_exists. Поки він червоний, роботу не приймуть. Спроби не обмежені: постав 600 і натисни перевірку ще раз.

.gitignore і .env.example

Якщо твій проєкт лежить у git, .env має бути в .gitignore до першого комміту. Файл .gitignore — це список того, що git ігнорує. Сам він у репозиторій їде, і в цьому сенс. Правило спрацює в кожного, хто клонує проєкт.

Разом із ним у репозиторій кладуть .env.example — той самий файл, але без значень. Він відповідає на питання «які змінні потрібні, щоб це запустилося», і не розкриває жодної.

Змінні оточення проти конфігу

Є два способи віддати програмі налаштування: покласти у файл конфігу або передати змінною оточення. У них різні сильні сторони.

.env — компроміс між ними. Це файл, який виглядає як список змінних оточення. Ідея прийшла з методології «Дванадцять факторів». Правило там просте: налаштування живуть окремо від коду. Код однаковий у всіх, а налаштування в кожного свої. Ми беремо це правило й робимо його найпростішим доступним способом.

Сканер секретів

Встав свій код — сторінка підсвітить рядки, які не можна нікуди віддавати

Такі самі інструменти працюють у GitHub і в багатьох CI. Змісту коду вони не розуміють. Вони шукають форму: довгі випадкові рядки й присвоєння змінним із підозрілими іменами. Тому й помиляються в обидва боки. Іноді підсвітять невинне, іноді пропустять справжнє. Останнє слово завжди за тобою.

Куди лягають дані: JSONL і межа веб-кореня

Два рішення, які приймають один раз і потім не переробляють

Чому JSONL, а не CSV

JSONL (JSON Lines) — це файл, у якому один рядок = один самодостатній JSON-об’єкт. Ніякої обгортки, ніякого масиву навколо, ніякої коми в кінці рядка.

А чому не один великий leads.json із масивом? Щоб додати запис у масив, треба прочитати весь файл, розібрати його, дописати елемент і переписати файл цілком. Два запити одночасно — і половина даних зникла. У JSONL дописування — одна операція. Система робить її атомарно: відкриває файл у режимі append і додає рядок у кінець.

~/data/ проти ~/www/data/

Nginx віддає по HTTP лише те, що лежить усередині DocumentRoot. Для тебе це тека ~/www/. Усе, що поза нею, з інтернету недосяжне в принципі. Не тому що заборонено. А тому що з адреси в браузері туди просто не веде жоден шлях.

Код: приймач, відправник і контракт

Три файли. Кожен рядок ти маєш уміти пояснити вголос

~/www/api/inbox.php

Кроки в коді пронумеровані так само, як гілки дерева рішень вище.

Що тут варто прочитати уважно:

• dirname(__DIR__, 2) — шлях до домашньої теки рахується від самого файлу. Не /home/koval.d.10b жорстко: скопіюєш код однокласнику — він запрацює й у нього;
• php://input — сире тіло запиту. $_POST тут порожній, бо PHP наповнює його лише для форм, а не для JSON;
• FILE_APPEND | LOCK_EX — дописати в кінець і на час запису замкнути файл, щоб два одночасні запити не переплелися;
• mb_substr — обрізаємо довжину одразу. Це не валідація, це межа: повну валідацію ти зробиш наступного уроку.

Apps Script: відправник

У Google теж є свій «.env» — Script Properties. Токен кладеш туди через меню налаштувань проєкту. У коді лишається саме звернення до нього.

~/www/api/README.md — контракт

Контракт — це відповідь на питання «як до тебе стукати». Без нього твій ендпойнт не зможе використати навіть ти сам за два тижні.

Перевірка руками: три curl

Запускай їх у SSH-сесії — там справжній curl. Заміни <логін> і <токен> на свої.

Практика: збери ланцюг

Кроки 1—2 — у браузері в Google, 3—6 — у SSH-сесії, 7—9 — у себе на комп’ютері, 10—16 — знову сервер і форма. Галочки зберігаються, сторінку можна закрити.

Автоперевірка

Чекер стукає до тебе тричі: без токена, з чужим токеном і з правильним. Далі дивиться права й місце файлів. Спроби не обмежені.

Демонстраційний режим: результат згенеровано для показу. На сервері ця кнопка викликає POST /api/check, який запускає check 02 від імені учня.

Що вчитель дивиться на твоєму екрані

• відкрита твоя Google-форма — з полями, а не порожня заготовка;
• журнал виконань Apps Script: видно, що запуск ішов від події «При надсиланні форми», а не з кнопки «Виконати» в редакторі;
• ти надсилаєш форму просто зараз, і в журналі з’являється рядок із кодом 200;
• у SSH ти показуєш tail -n 1 ~/data/leads.jsonl — останній рядок збігається з тим, що ти щойно ввів у форму;
• ls -l ~/.env читаєш уголос: хто власник і які три групи прав;
• у налаштуваннях Apps Script відкриваєш Script Properties — токен там, а не в тексті скрипта.

Шкала виконання

Це те, що бачить учитель, коли виставляє оцінку.

Чотири речення, які варто запам’ятати

• вебхук — це коли до тебе стукають; тому в тебе має бути публічна адреса і перевірка на вході;
• секрет живе в одному файлі поза www з правами 600, а в коді лишається лише звернення до змінної;
• дані лежать поза DocumentRoot, інакше їх віддає веб-сервер кожному охочому;
• код відповіді — це інструкція для програми: 401 «додай ключ», 403 «твій ключ не той», 422 «полагодь дані».

Де найчастіше помиляються

• токен продубльовано в Apps Script і в коментарі HTML «щоб не забути»;
• ~/.env створено з правами 644 — блокуючий критерій env_exists червоний;
• Apps Script шле application/x-www-form-urlencoded, а приймач чекає JSON — тихий 422 і жодного запису;
• leads.jsonl покладено в ~/www/data/ «щоб зручно дивитися» — блокуючий критерій data_outside червоний;
• тригер запускають кнопкою «Виконати» в редакторі — на очній здачі це видно одразу, бо в журналі немає події форми;
• теку ~/data/ не створили — приймач відповідає 200, а файл не з’являється.

Домашнє завдання

Допиши ~/www/api/README.md. Опиши всі коди відповіді свого приймача. І що кожен означає для того, хто стукає. Не «401 — помилка», а «401 — заголовка X-Auth-Token немає взагалі; треба дослати заголовок, повторювати без нього безглуздо».

Додай наприкінці абзац-гіпотезу до наступного уроку. Що станеться, якщо в поле «Ім’я» вставити <script>alert(1)</script>, а твоя сторінка потім покаже це ім’я?

Звідки взяті визначення й коди

Усе на цій сторінці — зі стандартів і офіційної документації. Перевіряти дозволено й корисно.

• HTTP-семантика: методи, заголовки й коди відповіді (RFC 9110) — першоджерело для 200, 401, 403, 405 і 422. rfc-editor.org/rfc/rfc9110
• 429 Too Many Requests (RFC 6585) — код і заголовок Retry-After. rfc-editor.org/rfc/rfc6585
• Довідник кодів відповіді HTTP, MDN — короткі пояснення до кожного. developer.mozilla.org/HTTP/Status
• Формат JSON (RFC 8259) і формат CSV (RFC 4180) — те, з чого випливає порівняння в розділі про JSONL. rfc8259, rfc4180
• JSON Lines — специфікація формату «один JSON на рядок». jsonlines.org
• Apps Script: UrlFetchApp.fetch — параметри method, contentType, headers, payload, muteHttpExceptions. developers.google.com/apps-script/reference/url-fetch
• Apps Script: встановлювані тригери — чому простий onFormSubmit не має права на UrlFetchApp. developers.google.com/apps-script/guides/triggers/installable
• Apps Script: PropertiesService — сховище властивостей скрипта, «.env» на боці Google. developers.google.com/apps-script/guides/properties
• PHP: parse_ini_file, hash_equals, file_put_contents — усе, що робить приймач. parse-ini-file, hash-equals, file-put-contents
• OWASP Secrets Management Cheat Sheet — чому секрети не тримають у коді й що робити, якщо секрет уже витік. cheatsheetseries.owasp.org
• The Twelve-Factor App, фактор III «Config» — конфігурація зберігається окремо від коду. 12factor.net/config
• GitHub: пошук секретів у репозиторіях — як знаходять залиті ключі й чому їх треба перевипускати. docs.github.com/secret-scanning
• gitignore, документація Git — синтаксис і чому пізнє правило не прибирає файл з історії. git-scm.com/docs/gitignore
• chmod і вісімкові права — man-сторінка. man7.org/chmod
• Nginx: директива root і межа веб-кореня — чому файл поза DocumentRoot недосяжний по HTTP. nginx.org/ngx_http_core_module#root
• Вебхук — загальне визначення і чим він відрізняється від опитування. en.wikipedia.org/wiki/Webhook
• Атака по часу порівняння рядків — навіщо hash_equals. en.wikipedia.org/wiki/Timing_attack

Повний список із поясненнями, що звідки взято, — у файлі urok-03-джерела.md поруч із цією сторінкою.