Короткий ответ
Webhook нужно проектировать как повторяемое событие, а не как одноразовый сигнал. Система должна безопасно принять дубликат, пережить временную недоступность и не выдать товар дважды.
- Быстро принимайте событие и фиксируйте его до тяжелой обработки.
- Проверяйте подлинность по актуальной документации.
- Разрешайте только допустимые переходы статусов.
- Храните журнал для расследования и сверки.
Почему уведомления повторяются
Провайдер может повторить доставку, если не получил своевременный успешный ответ. Сеть также может задержать запрос, а события по разным попыткам одного заказа могут прийти близко друг к другу. Это нормальные условия распределенной системы.
Поэтому обработчик не должен предполагать, что каждое уведомление уникально или приходит строго один раз. Уникальность обеспечивается вашей записью event_id или комбинацией доступных идентификаторов.
Как строить обработчик
Сначала проверьте техническую корректность и подлинность уведомления, затем найдите платеж, сравните ожидаемую сумму и сохраните событие. Обновление заказа и выдача результата должны выполняться атомарно или через надежную очередь.
Возвращайте ответ быстро. Отправку писем, генерацию документов и другие долгие операции выполняйте асинхронно после фиксации статуса.
- проверка источника по документации;
- поиск платежа по идентификатору;
- контроль суммы и валюты;
- идемпотентная запись события;
- однократное бизнес-действие.
Модель статусов
Не все статусы равнозначны. Технический «создан» не означает оплату, а возврат не должен переводить заказ обратно в «оплачен». Определите конечные и промежуточные состояния и разрешенные переходы.
Если пришло неизвестное значение, сохраните его для анализа и не выполняйте финансовое действие до уточнения. Не хардкодьте текстовые значения без сверки с актуальной документацией.
Восстановление после сбоев
Добавьте очередь повторной проверки платежей, которые долго остаются в промежуточном статусе. Сопоставляйте их с API и реестром, а результат фиксируйте в журнале.
Оповещение должно срабатывать на рост ошибок подписи, длительную очередь, повторные события и расхождения сверки. Это помогает обнаружить проблему раньше обращения покупателя.
Вопросы и ответы
Нужно ли отвечать webhook до обработки заказа?
Событие следует надежно зафиксировать и ответить быстро; тяжелые действия можно продолжить через очередь.
Можно ли доверять статусу из браузера?
Нет. Финансовый результат подтверждается проверенным серверным каналом или запросом статуса.
Что делать с неизвестным статусом?
Сохранить событие, не выполнять необратимое действие и свериться с актуальной документацией.
Источники и правила
Используем официальные материалы платежной системы и политики WHITECAPITAL. Для конкретного подключения приоритет имеют договорные документы.
Материал предназначен для операционной ориентации и не является обещанием подключения, универсальной доступности метода, фиксированной комиссии или срока расчетов.