Webhook: коли API дзвонить вам, а не ви йому
- Yuliia Asliaieva
- 15 бер.
- Читати 6 хв
Я, Yuliia Asliaieva, бізнес аналітик. За роки роботи з інтеграційними рішеннями у fintech, банкінгу та страховому домені я зрозуміла одну важливу річ: найскладніші технічні концепції можна і треба пояснювати просто. У своїй роботі з інтеграціями я часто бачу два підходи до обміну даними. Перший ->постійно перевіряти статус і перевантажувати систему. Другий ->використати Webhook. Що це простою мовою і чому нагадує послугу «ми вам передзвонимо» замість висіння на лінії? Давайте розбиратися.
Що таке Webhook простими словами?
Представимо, що ви замовили піцу і кожні 5 хвилин дзвоните в ресторан: - Готова піца? - Ні.
(Через 5 хвилин)
- А зараз готова? - Ні.
(Ще через 5 хвилин) - А зараз? - Ні, ще 10 хвилин!
Це називається Polling, коли ваш додаток постійно "ломиться" в API з запитом: "Є нові дані? А зараз? А зараз?" Це втомлює сервер, марнує ресурси і нерви всім.
А тепер уявіть інший сценарій:
Ви замовили піцу і ресторан каже: "Окей, як тільки піца буде готова — ми вам подзвонимо". Ви спокійно займаєтесь своїми справами, і от, нарешті, дзінь! Вам дзвонять: "Ваша піца готова, кур'єр їде до вас!"
Це і є Webhook, коли сервіс самостійно сповіщає вас, коли щось відбулося. Ви не питаєте та вам кажуть.
Webhook - це "зворотний дзвінок" від сервісу. Ви залишаєте свій "номер телефону" (URL вашого сервера), і коли відбувається певна подія, то вам автоматично приходить сповіщення з даними.
Ключова різниця:
🟤 Звичайний API (Request-Response):ВИ питаєте → СЕРВІС відповідає.Ініціатор -> ви. Ви контролюєте, коли робити запит, щоб отримати дані прямо зараз.
🟢 Webhook (Event-Driven):СЕРВІС -> щось сталося → автоматично відправляє дані → ВАШ СЕРВЕР.Ініціатор -> сервіс. Він сам вирішує, коли надіслати вам дані (за фактом події).
🔵 Polling (Опитування):ВИ питаєте: «Є щось?» -> СЕРВІС: «Ні» -> ВИ знову: «А зараз?» -> СЕРВІС: «Так».Ініціатор -> ви. Ви регулярно перевіряєте сервіс через певні проміжки часу, щоб дізнатися, чи не з'явилися нові дані. Використовується коли сервіс не підтримує Webhooks, а вам потрібно відстежувати зміни. Це «найважчий» метод для сервера, бо багато запитів йдуть впусту.
Давайте поглянемо на життєві приклади Webhook (ви їх точно використовуєте кожен день)
📱 Трекінг посилки
Без webhook (Polling): Ви кожні 10 хвилин відкриваєте сайт Нової Пошти і вводите ТТН: "Де моя посилка? А зараз де? А зараз?"
З webhook: Нова Пошта надсилає вам SMS або push: "Ваша посилка прибула у відділення". ВАМ дзвонять, а не ви їм.
💳 Платежі (Stripe, PayPal, LiqPay)
Користувач оплачує замовлення на сайті. Платіжна система обробляє платіж (це може зайняти 5-30 секунд). Замість того, щоб ваш сервер кожну секунду запитував "Оплатив? А зараз оплатив?", платіжна система сама надішле webhook: "Платіж успішний! Ось дані транзакції."
🎬 YouTube / Twitch
Ви підписалися на канал → YouTuber завантажив нове відео → Вам приходить сповіщення. Це і є webhook в дії.
💬 ChatBots (Telegram, Slack)
Користувач пише повідомлення в Telegram бота → Telegram не чекає, поки ваш сервер запитає "Чи є нові повідомлення?" → Telegram одразу відправляє webhook на ваш сервер з текстом повідомлення.
Анатомія Webhook або як це працює технічно
Крок 1: Реєстрація Webhook (Subscription)
Ви кажете зовнішньому сервісу:"Слухай, коли в тебе станеться подія X, то відправ мені дані сюди:"
POST https://api.service.com/webhooks{ "url": "https://myapp.com/webhooks/payment-received", "events": ["payment.success", "payment.failed"]}
Що ви передали:
url: ваш endpoint, куди сервіс має слати дані
events: які події вас цікавлять
Сервіс відповідає: "Окей, записав. Як тільки буде payment.success, то відправлю тобі дані."
Крок 2: Подія відбувається
Користувач оплатив замовлення → платіжна система зафіксувала це як подію payment.success.
Крок 3: Webhook викликається (Callback)
Платіжна система автоматично робить HTTP POST запит на ваш URL.
Крок 4: Ваш сервер обробляє webhook
Ваш backend отримує ці дані і далі:
Перевіряє підпис (X-Webhook-Signature), щоб переконатись, що це справді від платіжної системи, а не від хакера
Оновлює статус замовлення в базі даних: "ORDER-789 → PAID"
Відправляє email клієнту: "Дякуємо за покупку!"
Відповідає сервісу: 200 OK (щоб той знав, що ви успішно отримали дані)
Якщо ваш сервер не відповість 200 OK,то платіжна система подумає "Хм, вони не отримали дані" і спробує відправити webhook ще раз через 5 хв, потім через 15 хв, потім через годину... (Retry mechanism)
Webhook vs API: коли що використовувати?
Критерій | API (Request-Response) | Webhook (Event-Driven) |
Ініціатор | Ви запитуєте дані | Сервіс надсилає дані |
Коли використовувати | Коли ви контролюєте, коли потрібні дані | Коли події відбуваються непередбачувано |
Навантаження | Polling= багато запитів | Тільки коли щось сталося |
Real-time | Затримка ( залежить від частоти polling) | Майже миттєво |
Приклади | “Покажи список товарів”, “Дай інфо про користувача” | “Новий платіж”, “Email відкрито’, “Файл завантажено” |
Залежність | Ваш сервер робить запити | Ваш сервер приймає запити |
Оптимальне рішення - це гібридний підхід:
Використовуємо Webhook для миттєвої реакції на події (real-time).
Використовуємо API (Request-Response) для завантаження деталей, історії або уточнення даних за потребою (on-demand).
Така комбінація забезпечує актуальність даних без зайвого навантаження на систему.
Приклад для аналітиків: інтеграція з CRM
Представимо, що ви Бізнес аналітик на e-commerce проєкті. Вам треба інтегруватись з платіжною системою LiqPay.
Сценарій 1: Користувач оплачує замовлення
Без webhook (погана практика):
1. Користувач натискає "Оплатити";
2. Ваша система відправляє його на сторінку LiqPay;
3. Користувач платить;
4. LiqPay повертає його на ваш сайт;
5. Ваш backend кожні 5 секунд робить запит до LiqPay API: "Чи оплатив користувач USER123?";
6. LiqPay відповідає: "Ні", "Ні", "Ні", "Так!";
7. Ваша система оновлює статус замовлення.
Проблеми:
🔴 Якщо користувач закрив вкладку після оплати -> ваш сайт може не дізнатись про платіж.
🔴 Ви робите десятки зайвих запитів до API (можете вичерпати ліміт).
🔴 Затримка між реальною оплатою і оновленням статусу.
З webhook :
1. Користувач натискає "Оплатити";
2. Ваша система відправляє його на сторінку LiqPay;
3. Користувач платить;
4. LiqPay одразу надсилає webhook на ваш URL: POST https://yourdomain.com/api/webhooks/liqpay { "status": "success", "order_id": "123", "amount": 1500 };
5. Ваш backend миттєво оновлює статус замовлення;
6. Користувач повертається на сайт і бачить "Оплата успішна!"
Переваги:
✅ Миттєвість (0-2 секунди затримки);
✅ Надійність (навіть якщо користувач закрив вкладку);
✅ Економія API запитів;
✅ Ваша система отримує докладну інформацію про транзакцію.
Коли Webhook — це погана ідея?
Senior BA має вміти сказати "Ні", коли рішення не підходить. Webhook - це не "срібна куля". Іноді старий добрий REST API працює краще.
❌ 1. Коли дані потрібні "тут і зараз" (On demand)Якщо користувач натискає кнопку "Показати список користувачів", він не хоче чекати, поки сервер "передзвонить". Йому потрібна відповідь негайно.
Якщо ініціатором дії є клієнт, який чекає на екран, використовуйте звичайний GET API запит.
❌ 2. Коли ваш сервер "схований" від світу.Webhook -це вхідний дзвінок. Щоб отримати webhook, ваш сервер повинен мати публічну адресу (Public IP), яку "бачить" інтернет.
Якщо ваша система працює у закритому контурі безпеки (наприклад, внутрішня банківська мережа або тестовий сервер під VPN), зовнішній сервіс технічно не зможе надіслати туди дані.
Рішення: У таких випадках замість Webhook використовується Polling (коли ми самі періодично запитуємо дані; періодичне опитування: "Чи є щось нове?").
❌ 3. Коли потрібна миттєва зворотна відповідь.Webhook працює за принципом "повідомив і забув". Сервіс не чекає, що ви у відповідь на webhook одразу повернете якісь складні розрахунки.
Якщо зовнішній сервіс потребує даних від вас для продовження своєї роботи, то це має бути API виклик, а не webhook.
Чек-лист для Бізнес/Системного Аналітика: "Готовність до інтеграції"
Коли ви пишете вимоги для вебхуків, то пропоную цей список, щоб нічого не забути обговорити з розробниками:
🔹 1. Базові налаштування.
Endpoint URL: Яку адресу ми даємо партнеру?
Events List: На які саме події ми підписуємось?
Payload Structure: Чи є у нас приклад JSON, який прийде?
🔹 2. Безпека (Security).
Verification: Як ми перевіряємо зворотній виклик(Signature verification, secret token)?
Secret Management: Де зберігаємо ключ?
Failure Policy: Що робити, якщо підпис невірний? (Відхилити 400/401 + записати в лог).
🔹 3. Обробка та Логіка (Processing)
Idempotency: Як ми захищаємось від дублів?
Performance: Чи вкладаємось ми в тайм-аут (3-5 сек)?
Mapping: Як поля з вебхука лягають в нашу БД?
🔹 4. Помилки та Відновлення (Error Handling)
Retry Policy: Якщо ми впали, скільки разів сервіс спробує надіслати дані знову?
Not Found Scenarios: наприклад от що робити, якщо прийшла оплата за замовлення, якого немає в нашій базі?
Підсумую: Webhook - це "не дзвони нам, проте ми подзвонимо тобі"
Щоб запам'ятати різницю, проведу аналогію з рестораном:
📞 Класичний API - це коли ви дзвоните в ресторан і питаєте: "Мій столик вже готовий?". Ви чекаєте на лінії, поки адміністратор перевірить. Ви ініціюєте контакт.
🔔 Webhook- це коли ви залишаєте свій номер і кажете: "Подзвоніть мені, коли столик звільниться". Ви гуляєте в парку, а ресторан сам "смикає" вас, коли настає подія.
Новини та статті з бізнес-аналізу:
