Описание
Webhooks VPOS.am передают события платежей, фискализации и сверки с подписью, retries и требованиями к идемпотентной обработке.
Минимальный безопасный handler
Обработчик принимает событие, проверяет подпись, сохраняет payload и event id, отвечает быстро, а тяжелую бизнес-логику передает в очередь. Это снижает риск timeout и повторной доставки.
Изменять заказ, счет или статус клиента до проверки подписи нельзя. Если подпись невалидна, событие отклоняется и фиксируется в журнале безопасности.
Повторы и временные ошибки
Повтор webhook не должен быть ошибкой для бизнес-логики. Если event id уже обработан, handler возвращает успешный ответ или безопасный текущий результат без повторного создания сущностей.
Если CRM, ERP или фискальный сервис недоступны, событие сохраняется и повторяется через очередь. Ошибка должна быть видна оператору, а не теряться в логах сервера.
Какие события стоит разделять
Платежные события, фискальные события и события сверки лучше обрабатывать раздельно. У них разные последствия: одно меняет заказ, другое выпускает чек, третье создает задачу на ручную проверку.
Такой подход делает интеграцию понятнее для разработчиков, операционного отдела и бухгалтерии.
Частые вопросы
Что должен сделать webhook handler до изменения заказа?
Он должен проверить подпись, сохранить event id и payload, убедиться, что событие еще не обработано, и только после этого менять заказ, счет, fiscal job или CRM-статус.
Почему тяжелую бизнес-логику лучше переносить в очередь?
Webhook endpoint должен ответить быстро. Очередь позволяет повторить CRM, ERP, e-mail или fiscal действия при временной ошибке и не потерять событие из-за timeout.