Webhooks vs Polling: как не устроить консистентный ад на стейтах платежей

Webhooks vs Polling: как не устроить консистентный ад на стейтах платежей

Webhooks — это не «магия real-time», а доставка событий с чужой гарантией. Polling — не «надёжный план Б», а тупой опрос API, который жрёт лимиты и размазывает задержку. В платежах оба подхода живут, пока вы не начнёте путать факт смены статуса с фактом доставки сообщения.

Если у вас webhook-first, проверяйте не payload, а контракт:
— идемпотентный consumer;
— подпись и timestamp, иначе вам шлют мусор под видом платежа;
— обработка дублей и out-of-order событий;
— повторная доставка без побочных эффектов.

Если у вас polling-first, не делайте вид, что «раз в N секунд» решает консистентность. Он нужен только как страховка, когда вебхук не пришёл, а не как источник истины. Иначе получите классический зоопарк: платеж уже captured, а в вашей базе всё ещё pending. Документация — это ложь, логи — истина.

Нормальная схема почти всегда гибридная: вебхук двигает стейт, polling добирает хвосты, reconciliation ловит расхождения. Для спорных статусов держите отдельный job, который сверяет авторизацию, холд, capture и refund по merchant reference, а не по красивому display-id.

Идемпотентность или смерть: если ваш стейт-машин не переживает дубль, потерю и перестановку событий, интеграция уже сломана.