Вебхук Monobank Acquiring: перевірка підпису ECDSA і чому сире тіло запиту має значення

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

Monobank підписує вебхук асиметрично: приватним ключем підписує він, а ви перевіряєте його ПУБЛІЧНИМ ключем, який отримуєте окремим запитом. Спільного секрету немає взагалі. Це строго краще з погляду безпеки — навіть повний злив вашої бази не дає можливості підробити подію, — але вимагає двох речей, яких HMAC-схема не вимагає: правильної роботи з сирим тілом запиту й кешування публічного ключа.

Контракт

Помилка перша: розібрати JSON до перевірки підпису

Підпис накладено на конкретну послідовність байтів. Якщо ваш фреймворк автоматично розбирає тіло в обʼєкт, а ви потім серіалізуєте його назад, щоб перевірити підпис, — ви перевіряєте вже інші байти. Порядок ключів, пробіли, представлення чисел, екранування не-ASCII: будь-що з цього може відрізнятися, і воно відрізняється.

Найгірший сценарій тут не «нічого не працює», а «працює на тестових даних і падає на реальних»: простий payload після round-trip випадково збігається, а той, у якому є українські символи в імені покупця або дробова сума, — вже ні.

Правило одне: прочитати тіло як сирий текст, перевірити підпис на ньому, і лише потім розбирати. У Next.js Route Handler це `await request.text()` перед будь-яким `request.json()` — другий виклик на тому самому запиті вже недоступний, тож порядок тут не стилістичний.

Помилка друга: тягнути публічний ключ на кожен вебхук

Публічний ключ мерчанта змінюється рідко, а запит по нього коштує роундтрипу до Monobank і витрачає ваш ліміт. Робити його на кожну оплату — гарантований спосіб отримати збої під навантаженням саме тоді, коли оплат багато.

Але і кешувати назавжди не можна: ключ усе ж може бути перевипущений, і тоді жорсткий кеш означає, що ви перестаєте приймати оплати до наступного деплою.

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

Окремо варто сказати очевидне, що часто роблять неправильно: публічний ключ — це НЕ секрет. Його не треба шифрувати в базі. Він потрібен лише щоб перевіряти підписи, і його знання нікому нічого не дає. Шифрувати належить X-Token, яким ви цей ключ отримуєте.

Перевірка, яка справді захищає

• Перевірка провалилася — відхиляємо запит. Не логуємо й не пропускаємо далі «на всяк випадок»: вебхук без валідного підпису це не подія, а невідомий, який каже, що вам заплатили.
• Ключ не вдалося отримати або розшифрувати X-Token — теж відхиляємо. Fail-closed: недоступність перевірки не є підставою довіряти неперевіреному.
• Порівнюйте також id мерчанта з конфігурації адаптера — так подія від чужого акаунта не потрапить у ваш простір навіть за валідного підпису.
• Запис оплати робіть ідемпотентним за id рахунку: банк має право доставити ту саму подію двічі, і це нормальна поведінка, а не збій.
• Не зберігайте номер картки й CVV. Для звірки достатньо суми, валюти, статусу й id рахунку — а те, чого немає в базі, не може витекти.

Куди подіти оплату, яка не знайшла замовлення

Підпис перевірено, сума є, а reference не збігається ні з чим. Найпоширеніша реакція — відкинути подію: 200 у відповідь, нічого не записано. Це найгірше з можливих рішень, бо гроші вже прийшли, і тепер їхнього сліду в системі немає.

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

Часті запитання