Що таке вебхук: як працюють вебхуки, приклади та поради з безпеки

Вебхук (webhook) — це спосіб, у який один сервіс повідомляє інший у момент, коли щось відбувається. Замість того щоб ваш застосунок кожні кілька секунд питав провайдера «чи є щось нове?», провайдер сам надсилає HTTP-запит на обрану вами адресу одразу після події: платіж пройшов, форму надіслано, прийшло повідомлення, збірка завершилася.

Вебхуки працюють у великій частині сучасного вебу: підтвердження платежів, чат-боти, інструменти автоматизації на кшталт n8n чи Zapier, конвеєри розгортання, сповіщення моніторингу. У цьому посібнику пояснено, як вони працюють, чим відрізняються від звичайного виклику API і як безпечно їх приймати.

Опитування чи вебхуки

При опитуванні (polling) ваш код раз у раз звертається до API, щоб перевірити зміни. Це просто, але більшість таких запитів нічого нового не повертає, вони витрачають ваш ліміт запитів, а оновлення запізнюються на інтервал опитування.

З вебхуком напрямок протилежний. Ви один раз даєте провайдеру URL, і він звертається до вас лише тоді, коли є що повідомити. Оновлення приходять за секунди, і жоден запит не марнується. Легко запам’ятати так: API — це ви дзвоните сервісу; вебхук — сервіс передзвонює вам.

Як працює вебхук, крок за кроком

1. Ви створюєте точку прийому — URL на своєму сервері, наприклад https://example.com/hooks/payments, що приймає POST-запити.
2. Ви реєструєте її у провайдера й обираєте потрібні події: payment.succeeded, order.created тощо. Зазвичай провайдер видає секрет для перевірки підписів.
3. Відбувається подія на боці провайдера.
4. Провайдер надсилає POST-запит на ваш URL із JSON-тілом, що описує подію.
5. Ваш сервер перевіряє й підтверджує його, швидко відповідаючи кодом 2xx, а потім обробляє подію.
6. Якщо ви не відповіли 2xx, більшість провайдерів повторює спробу пізніше — часто годинами чи днями, зі зростаючими паузами.

Типова доставка виглядає так:

POST /hooks/payments HTTP/1.1
Content-Type: application/json
X-Signature: t=1760880000,v1=5f2b9c...

{
  "id": "evt_8421",
  "type": "payment.succeeded",
  "created": 1760880000,
  "data": { "payment_id": "pay_193", "amount": 2500, "currency": "EUR" }
}

Де трапляються вебхуки

• Платежі – платіжний провайдер підтверджує, що гроші справді надійшли, а також повідомляє про повернення й спори.
• Месенджери й боти – Telegram, Slack та інші платформи можуть доставляти нові повідомлення боту через вебхук замість довгого опитування.
• Хостинг коду – GitHub і GitLab надсилають події push, merge request і pipeline в CI-системи та чати.
• Автоматизація – інструменти на кшталт n8n запускають сценарій, коли викликають URL вебхука.
• Моніторинг – сервіси перевірки доступності й системи сповіщень надсилають інциденти в чат.

Захист точки прийому

URL вебхука доступний публічно, тож будь-хто, хто його дізнається, може надсилати фальшиві події. Вважайте кожен вхідний запит недовіреним, доки не перевірите.

Перевіряйте підпис

Більшість провайдерів підписують кожен запит спільним секретом за допомогою HMAC-SHA256 і кладуть результат у заголовок. Обчисліть підпис із сирого тіла запиту й порівняйте за сталий час:

import crypto from 'node:crypto';

function isValid(rawBody, header, secret) {
  const [tPart, sigPart] = header.split(',');
  const timestamp = tPart.split('=')[1];
  const expected = crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  const given = sigPart.split('=')[1];
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

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

Інші заходи

• Лише HTTPS, щоб тіло й підпис не можна було прочитати чи змінити дорогою. Див. HTTP і HTTPS.
• Шлях, який важко вгадати, допомагає, але не замінює підпис.
• Не довіряйте вмісту наосліп. Для важливих подій, як-от платіж, отримайте об’єкт з API провайдера за його ID, перш ніж відвантажувати товар чи надавати доступ.
• Тримайте секрет поза кодом: у змінних середовища чи менеджері секретів, і змінюйте його, якщо він витік.

Надійність: дублі, порядок і тайм-аути

• Відповідайте швидко. Провайдери чекають лише кілька секунд. Збережіть подію, відповідайте 200, а важку роботу виконуйте у фоновому завданні.
• Чекайте дублів. Через повтори та сама подія може прийти двічі. Зберігайте ID оброблених подій і пропускайте повтори — тоді обробник буде ідемпотентним.
• Не покладайтеся на порядок. Подія «оновлено» може прийти раніше за «створено». Використовуйте мітки часу або перечитуйте актуальний стан з API.
• Плануйте простої. Якщо сервер лежить довше, ніж провайдер повторює спроби, події втрачаються. Багато провайдерів дозволяють переглянути чи повторно надіслати минулі події — використовуйте це для звірки.
• Логуйте доставки з ID події, типом і результатом. Коли щось зламається, лог буде першим місцем, куди ви подивитеся.

Тестування вебхуків локально

Ваш ноутбук недоступний з інтернету, тож провайдер не може звернутися до нього напряму. Поширені варіанти: власний CLI провайдера, що пересилає події на localhost; інструмент тунелювання, що дає тимчасову публічну URL; сервіс перегляду запитів, де видно справжнє тіло. У багатьох панелях є кнопка «надіслати тестову подію». Вимикайте тимчасові тунелі після тестування.

Вебхуки чи WebSocket

Обидва способи доставляють оновлення без опитування, але для різних задач. Вебхук — це окремий HTTP-запит від сервера до сервера на кожну подію, ідеальний для серверних інтеграцій. WebSocket — довготривале з’єднання, яким іде потік повідомлень, ідеальне для живих панелей, чатів і цін у браузері чи застосунку.

Головне

• Вебхук — це зворотний HTTP-виклик: сервіс звертається до вашої URL, коли стається подія.
• Він економить запити й доставляє оновлення швидше, ніж опитування.
• Завжди перевіряйте підпис, використовуйте HTTPS і звіряйте важливі події з API.
• Відповідайте швидко, обробляйте дублі й логуйте все.

Читайте також: що таке API, що таке REST API і API-ключ чи OAuth.