Stripe webhook: перевірка підпису та повторних повідомлень

Зв’яжіть подію з бізнесовим об’єктом

До написання обробника визначте, які події потрібні вашому сценарію та який об’єкт вони змінюють. Замовлення, платіжна спроба й виконання послуги повинні мати окремі записи. Подія провайдера описує його об’єкт; ваш сервер має зіставити цей об’єкт із внутрішнім замовленням і перевірити, що сума, валюта та акаунт відповідають очікуванню.

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

Платіжні вебхуки

Перевіряйте підпис за протоколом джерела

Використовуйте офіційну документацію Stripe для перевірки підпису, включно з вимогами до тіла запиту та секрету кінцевої точки. Не змінюйте тіло повідомлення до перевірки у спосіб, який порушує її коректність. Секрет не повинен потрапляти до браузера, публічного репозиторію або звичайного журналу помилок. Відокремлюйте налаштування тестового та робочого середовищ.

Stripe, Adyen і OrsunPay не є взаємозамінними протоколами підпису. Власні повідомлення OrsunPay використовують HMAC, а прямі повідомлення провайдера потрібно перевіряти за його правилами. Якщо сервер приймає обидва джерела, розділіть їх конфігурацію та перевірку. Не використовуйте успішну перевірку одного формату як доказ автентичності іншого, навіть коли зміст подій виглядає подібним.

Інструменти розробника

Збережіть подію перед складними діями

Після автентифікації та базової перевірки даних зафіксуйте подію в надійному сховищі. Важкі операції, як-от формування документа або надсилання кількох листів, краще виконувати окремим контрольованим процесом. Відповідь обробника повинна відповідати фактичному прийняттю події, а не приховувати помилку запису, яка призведе до втрати інформації.

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

Захистіть зміну стану від повторення

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

Окремо врахуйте порядок подій. Старіше повідомлення не повинно без перевірки перезаписати остаточний стан новішої операції. Якщо дані суперечать поточному стану, перевірте авторитетний об’єкт або передайте випадок на розгляд. Правило «останній отриманий запит перемагає» зручне для простого коду, але небезпечне для асинхронної платіжної історії та розслідування звернень.

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

Створіть набір сценаріїв, у яких видно очікуваний стан замовлення після кожної події. Не обмежуйтеся позитивним прикладом з документації. Офіційні інструкції Stripe та Adyen описують власні механізми вебхуків; використовуйте їх для правильного налаштування джерел, а бізнесові правила перевіряйте окремо у своїй системі.

• Відхиліть повідомлення з неправильним підписом без зміни замовлення.
• Надішліть однакову подію двічі та перевірте одноразове виконання.
• Перервіть обробку після збереження й перевірте безпечне відновлення.
• Зіставте пізнє повідомлення з уже відомим успішним результатом.

Дайте підтримці можливість пояснити затримку

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

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

Джерела

• Stripe — Вебхуки
• Adyen — Вебхуки