Webhook

Що це означає

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

Від API він відрізняється напрямком. API ми питаємо самі, коли щось потрібно; вебхук приходить сам, без повторюваних запитів з боку системи.

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

Як це працює на практиці

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

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

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

На що звернути увагу

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

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