Що таке webhook? Як застосунки повідомляють один одного

Webhook — це автоматичне повідомлення, яке один сервіс надсилає вашому застосунку в той момент, коли щось сталося. Коли оплата клієнта проходить, Stripe надсилає webhook на адресу у вашому застосунку з повідомленням «оплату успішно проведено, ось деталі», і ваш застосунок реагує — позначає замовлення як оплачене, надсилає чек, відкриває доступ до акаунта. Коротко: API — це коли ваш застосунок ставить іншому сервісу запитання; webhook — це коли інший сервіс викликає ваш застосунок, щоб щось повідомити.

Чому це важливо, коли ви створюєте з ШІ

Щойно ваш застосунок приймає оплати, отримує надіслані форми від іншого інструмента або під'єднується до таких сервісів, як GitHub, Shopify чи календар, ви зіткнетеся з webhooks. Зазвичай саме це правильний спосіб дізнатися, що щось сталося, — але саме тут застосунки, створені з ШІ, найчастіше помиляються непомітно:

• Ендпоінт приймає будь-який запит, тож будь-хто може підробити подію «оплата успішна».
• Застосунок надає доступ на сторінці перенаправлення після оплати, а не через webhook, тож люди, які закрили вкладку раніше, не отримують того, за що заплатили, а ті, хто знайшов адресу успішної оплати, отримують доступ безкоштовно.
• Одна й та сама подія приходить двічі, і клієнт отримує два замовлення або два листи.

Знання того, як працюють webhooks, дає змогу заздалегідь попросити про захист.

Побутова аналогія: SMS про доставку

Дізнатися, чи прибула ваша посилка, можна двома способами. Можна щохвилини виходити до дверей і перевіряти (це polling — ваш застосунок багаторазово викликає API, щоб запитати «щось нове є?»). Або кур'єр може надіслати вам SMS, коли доставить (це webhook).

SMS явно краще — якщо ви можете йому довіряти. Якщо будь-хто міг би надіслати вам повідомлення «посилку доставлено», вам потрібен спосіб переконатися, що його справді надіслав кур'єр. А якщо ваш телефон був вимкнений, коли прийшов SMS, вам потрібно, щоб кур'єр спробував ще раз пізніше. Ці два питання — перевірка і повторні спроби — становлять більшість складності webhooks.

Як працює webhook, крок за кроком

1. Ви створюєте ендпоінт у бекенді вашого застосунку: URL, наприклад https://yourapp.com/webhooks/stripe, який приймає запити POST.
2. Ви реєструєте цю адресу у провайдера і обираєте, які події хочете отримувати (наприклад, «оплату завершено» і «підписку скасовано»).
3. Провайдер видає вам секрет для підпису. Ви зберігаєте його як секрет на сервері — див. змінні середовища та секрети.
4. Відбувається подія. Провайдер надсилає HTTP-запит на вашу адресу з JSON-тілом, що описує подію, і заголовком підпису.
5. Ваш застосунок перевіряє підпис, записує ідентифікатор події, швидко відповідає кодом успіху (200), а потім виконує роботу.
6. Якщо ваш застосунок не відповів успіхом, багато провайдерів пробують знову пізніше.

Підписи

Підпис доводить, що запит надійшов від провайдера і не був змінений. Наприклад, Stripe обчислює HMAC (різновид ключового відбитка) з SHA-256 від тіла запиту і часової мітки, використовуючи секрет для підпису, і надсилає його в заголовку Stripe-Signature. Ваш застосунок виконує ті самі обчислення зі своєю копією секрету; якщо результати збігаються, запит справжній. Оскільки часова мітка також підписана, ви можете відхиляти старі запити, які хтось записав і відтворив пізніше — бібліотеки Stripe за замовчуванням використовують допуск п'ять хвилин, за документацією станом на вересень 2026 року.

Одна практична деталь: підпис обчислюється від сирого тіла запиту. Якщо ваш фреймворк розбирає і переформатує JSON до перевірки, перевірка не пройде. Це дуже поширена помилка.

Повторні спроби, дублікати і порядок

Провайдери відрізняються, тож перевіряйте документацію кожного. Станом на вересень 2026 року:

Документація Stripe також говорить, що події не гарантовано приходять у тому порядку, в якому відбулися, і що та сама подія інколи може прийти більше ніж один раз, тому радить відстежувати ідентифікатори подій.

Загальний висновок справедливий для будь-якого провайдера: події можуть прийти із запізненням, більше ніж один раз і не за порядком. Обробник має бути ідемпотентним — обробка тієї самої події двічі має той самий ефект, що й обробка один раз.

Практичний приклад: відкриття доступу до платного курсу

Ви продаєте онлайн-курс. Студент натискає Купити, платить на сторінці оплати Stripe і повертається на ваш сайт.

Крихкий спосіб: сторінка «дякуємо» відкриває курс. Якщо студент закриє браузер під час переходу, він заплатив, але доступу немає. Якщо хтось вгадає адресу сторінки «дякуємо», він отримає доступ без оплати.

Спосіб через webhook:

1. Коли Stripe підтверджує оплату, він надсилає подію checkout.session.completed на /webhooks/stripe.
2. Ваш бекенд перевіряє підпис секретом для підпису. Якщо перевірка не проходить, він відповідає 400 і нічого не робить.
3. Він перевіряє, чи цей ідентифікатор події вже оброблено. Якщо так, відповідає 200 і зупиняється.
4. Він зберігає ідентифікатор події, відповідає 200, а потім відкриває студентові доступ і надсилає лист-привітання.
5. Сторінка «дякуємо» лише повідомляє: «Оплату отримано — ваш курс з'явиться за мить» і перевіряє статус доступу студента.

Пізніше, якщо підписку скасовано або картка відхилена, інші події webhook повідомляють вашому застосунку, щоб він прибрав або призупинив доступ. Так продукти за підпискою залишаються синхронними з біллінгом — див. що таке SaaS і як додати оплати до вашого застосунку.

Ключові терміни

• Ендпоінт: адреса у вашому застосунку, яка приймає webhooks.
• Подія / payload: що сталося, і дані, що це описують (зазвичай JSON).
• Секрет для підпису: спільний секрет, який використовується для перевірки підписів.
• Ідемпотентний: безпечний для повторного виконання з тим самим результатом.
• Polling: багаторазове запитування API про зміни замість очікування webhook.
• Тунель: інструмент, що дає ноутбуку тимчасову публічну адресу, щоб webhooks могли до нього дійти під час розробки.

Поширені помилки і хибні уявлення

• Неперевірені підписи. Адреса ендпоінта не є секретом. Саме перевірка робить запит довіреним.
• Повільна робота до відповіді. Надсилання листів або генерація PDF до відповіді може призвести до тайм-аутів, які викликають повторні спроби, які створюють дублікати.
• Припущення «рівно один раз, за порядком». Записуйте ідентифікатори подій і не покладайтеся на порядок надходження.
• Використання адреси попереднього перегляду. Webhooks потребують стабільної публічної адреси. Приватні попередні перегляди і localhost недоступні з інтернету; використовуйте опубліковану адресу (або тунель під час тестування).
• Змішування тестових і бойових секретів. Провайдери часто видають різні секрети для підпису в тестовому і бойовому режимах. Зберігайте обидва і використовуйте правильний.
• Сліпа довіра даним у payload для важливих рішень. Для дій з високими ставками розумно після отримання події запитати останній стан через API провайдера.

Що попросити у вашого ШІ-конструктора

Додай на сервері ендпоінт POST /webhooks/stripe. Перевір підпис Stripe, використовуючи сире тіло запиту і секрет STRIPE_WEBHOOK_SECRET. Відхиляй недійсні підписи з кодом 400. Зберігай ідентифікатор кожної події і пропускай ті, що вже оброблені. Швидко відповідай 200, а потім обробляй checkout.session.completed, позначаючи замовлення оплаченим і надсилаючи чек. Логуй тип події. Не відкривай доступ зі сторінки успішної оплати.

Потім перевірте: надішліть тестову подію з панелі провайдера, надішліть ту саму ще раз і надішліть запит з неправильним підписом. Змінити щось має лише перша.

Webhooks у Mythex

У Mythex немає окремого сервісу webhooks; ви просите агента додати ендпоінт webhook у власному бекенді вашого застосунку і вказуєте провайдеру вашу опубліковану адресу, бо webhooks потребують публічної адреси. Секрет для підпису йде в секрети проєкту, і якщо ви його змінюєте в живому застосунку, публікуйте знову. Рецепт з документації про обробку webhooks містить стартовий промпт, а шаблони магазинів — добра відправна точка для застосунків, що приймають оплати.

Запитання