Що таке вебхук і як обробляти сповіщення про оплату
Вебхук (webhook) — HTTP-запит, який сервіс сам надсилає на ваш сервер, щойно відбувається подія, наприклад оплата чи зміна статусу.
Замість того щоб щохвилини питати API «чи оплачено замовлення?», ви вказуєте URL, на який сервіс надішле POST-запит з даними події. Це і є вебхук. Для платежів типові події — платіж створено, отримано, підтверджено, прострочено, виплату виконано.
Вебхук — головне джерело правди для видачі товару. Повернення клієнта на сайт після оплати ненадійне: він може закрити вкладку, а посилання повернення можна підробити. Видавайте товар лише після вебхука з фінальним статусом і, за бажанням, повторно перевіряйте статус через API.
Надійна обробка має кілька правил. Перевіряти підпис запиту, щоб відсікти підробки. Відповідати 2xx швидко і робити важку роботу у фоні, інакше сервіс вирішить, що доставка не вдалася. Бути ідемпотентним: той самий вебхук може прийти двічі, і товар не повинен видатися двічі. Не покладатися на порядок доставки — події можуть прийти не за хронологією.
Типові помилки: приймати вебхук без перевірки підпису; парсити й повторно серіалізувати JSON перед перевіркою HMAC (підпис перестає збігатися); відповідати 500 через помилку в бізнес-логіці і отримувати нескінченні повтори; не мати логів і не розуміти, що прийшло. Ще одна пастка — обробник за редиректом чи авторизацією: вебхук приходить від сервера шлюзу без cookies, тож URL має бути доступним без входу в систему.
Moonvex підписує вебхуки HMAC у заголовку Moonvex-Signature, повторює доставку до трьох днів у разі помилки та зберігає журнал доставок у кабінеті, де видно кожну спробу й відповідь вашого сервера.
Чекліст обробника вебхуків
- Перевіряти підпис за «сирим» тілом запиту.
- Швидко відповідати 2xx, обробку робити у фоні.
- Зберігати ID події та ігнорувати дублікати.
- Перевіряти суму та статус, а не лише факт виклику.
- Логувати вхідні запити для розбору інцидентів.