Завершение криптовалютного платежа клиентом — лишь начало процесса. Вашему сайту или приложению еще необходимо подтвердить результат, обновить нужный заказ, уведомить клиента и определить, можно ли приступать к исполнению заказа. Именно вебхуки OxaPay позволяют сделать это, отправляя обновления статуса платежа непосредственно на сервер.
Надежная интеграция вебхуков — это не просто получение уведомлений. Она проверяет подлинность обратного вызова, сопоставляет его с нужным платежом, безопасно обрабатывает повторную доставку и запрашивает статус при задержке или неопределенности информации. В руководстве весь процесс практически объясняется владельцам бизнеса, продуктовым командам и разработчикам.
Что делает вебхук OxaPay
Вебхук — это сообщение между серверами, отправляемое при наступлении события. Вместо того чтобы ваша система постоянно проверяла, изменился ли платеж, OxaPay отправляет JSON-уведомление на указанный вами HTTPS-адрес, когда появляются новые сведения о платеже.
Приложение может использовать проверенное обновление, чтобы изменить статус заказа, активировать услугу, отправить подтверждение или создать запись для сверки. Это особенно полезно, поскольку криптовалютный платеж может пройти несколько состояний до окончательного результата для бизнеса.
Страницу возврата в браузере нельзя считать доказательством оплаты. Клиент может закрыть страницу, потерять соединение или перейти по URL возврата, хотя платеж еще не достиг необходимого состояния. Решение об исполнении заказа должно основываться на проверенных сервером платежных данных.
Когда бизнесу нужен платежный вебхук
Собственный вебхук особенно полезен, когда результат платежа должен автоматически запускать другое действие. Например:
- переводить заказ интернет-магазина из состояния ожидания в готовность к исполнению;
- активировать учетную запись SaaS или продлевать подписку;
- отправлять подтверждение оплаты по электронной почте, SMS или в приложении;
- обновлять остатки, CRM, бухгалтерские системы или внутреннюю отчетность;
- уведомлять операционную команду, когда платеж проведен не полностью или просрочен, либо требует проверки по другой причине.
Если вы используете поддерживаемый платежный плагин, значительная часть этой логики уже может быть реализована. Если вы лишь изредка создаете Payment Links and review them manually, you may not need a custom endpoint. Прямые API-интеграции and custom platforms usually benefit the most.
Как работает процесс вебхуков OxaPay
- Your system creates or identifies a payment and stores OxaPay’s
track_idwith your own order or customer reference. - Клиент отправляет платеж, и его статус меняется по мере обработки в OxaPay.
- OxaPay отправляет подписанное JSON-уведомление на настроенный URL обратного вызова.
- Ваш сервер проверяет подпись, прежде чем доверять сообщению.
- Сервер связывает уведомление с правильной записью и проверяет важные параметры платежа.
- Приложение записывает событие, однократно выполняет каждое разрешенное бизнес-действие и возвращает успешный HTTP-ответ.
Такое разделение важно. Вебхук доставляет обновление платежа, но именно ваше приложение решает, что оно означает для заказа, учетной записи, отправки товара или бухгалтерской проводки.
Перед началом
Перед подключением обратного вызова подготовьте следующее:
- публично доступный HTTPS-эндпоинт, принимающий HTTP POST-запросы;
- серверный доступ к соответствующим учетным данным мерчанта OxaPay, которые надежно хранятся и никогда не раскрываются в коде браузера;
- запись в базе данных, связывающую идентификатор OxaPay
track_idwith your own order, invoice, or user ID; - четкие правила, определяющие, какие статусы платежа могут запускать исполнение заказа, предоставление доступа, возврат, уведомление или ручную проверку;
- журналирование и мониторинг, позволяющие выявлять сбои доставки, ошибки проверки и неожиданные изменения статуса.
Если вы планируете более широкую интеграцию, воспользуйтесь контрольным списком интеграции криптовалютных платежей to review keys, payment methods, callbacks, testing, and go-live controls together.
Как настроить вебхуки OxaPay
Определите правила для статусов платежа
До написания обработчика решите, что ваш бизнес должен делать при каждом статусе платежа before writing the handler. A notification that a payment has started is not the same as a completed payment. Underpaid, expired, refunded, or other exception states may require a different action or a manual review.
Разрешайте только документированные и ожидаемые переходы между состояниями. Например, уже исполненный заказ не должен исполняться повторно из-за второй доставки того же уведомления.
Создайте защищенный эндпоинт обратного вызова
Создайте отдельный HTTPS-маршрут в серверной части приложения, например https://example.com/webhooks/oxapay. Он должен принимать POST-запросы, предоставлять исходное тело запроса для проверки подписи и отклонять неподдерживаемые методы или некорректные запросы.
Не перегружайте обработчик. Его первая задача — проверить уведомление и надежно сохранить его. Медленные операции, такие как отправка писем, обновление нескольких внешних систем или создание отчетов, можно перенести в фоновую очередь после принятия события.
Передайте URL обратного вызова в OxaPay
Добавьте URL обратного вызова в соответствующий платежный сценарий OxaPay. В зависимости от продукта или способа интеграции URL может передаваться в запросе на создание платежа либо задаваться в настройках мерчанта. Точное поле и поведение сервиса уточняйте в документации Webhook OxaPay for the exact field and behavior of the service you are implementing.
Последовательно используйте один URL в пределах каждой среды. Разделяйте тестовые и рабочие эндпоинты, чтобы тестовые события не изменяли реальные заказы.
Проверяйте подпись, прежде чем доверять уведомлению
В документации OxaPay описана подпись HMAC-SHA512, создаваемая на основе исходных POST-данных с использованием API-ключа мерчанта в качестве общего секрета. Сервер должен вычислить ожидаемую подпись по неизмененному телу запроса и сравнить ее с подписью в уведомлении.
При неудачной проверке отклоняйте запрос. Если фреймворк поддерживает такую возможность, используйте сравнение за постоянное время и никогда не записывайте API-ключ мерчанта или другие секреты. Разбор JSON с последующей повторной сериализацией перед расчетом HMAC может изменить пробелы или порядок полей и привести к отклонению правильной подписи. Справочник по проверке обратных вызовов explains the broader security model.
Сопоставьте и проверьте платеж
Действительная подпись подтверждает источник сообщения, но приложение все равно должно проверять бизнес-данные. Сопоставьте идентификатор track_id to a known payment record, confirm the relevant order or customer reference, compare the expected amount and currency where applicable, and check that the new state is allowed from the current state.
Не допускайте автоматического исполнения заказа при неизвестном платеже, неожиданной сумме или недопустимом переходе состояния. Запишите событие для расследования и подтвердите текущие сведения о платеже через API.
Обрабатывайте каждое событие идемпотентно
Вебхуки могут доставляться повторно. При повторном получении одного и того же обновления обработчик должен давать одинаковый конечный результат. Сохраните устойчивый ключ события или состояния платежа и проверяйте его перед отправкой письма, предоставлением доступа, изменением остатков или созданием бухгалтерской записи.
Идемпотентность превращает повторную доставку в безвредную попытку, а не в повторную отправку товара, многократное продление подписки или дублирование проводки.
Сохраните событие и быстро ответьте
После проверки запроса сохраните уведомление и результат валидации, прежде чем возвращать HTTP 200 with the expected ok response. If downstream work may take time, place it in a queue and respond after durable receipt rather than making the sender wait for the entire business workflow.
Если сервер не может безопасно сохранить событие, верните ошибку и выясните причину. Не подтверждайте получение уведомления, чтобы затем незаметно его отбросить.
Протестируйте полный жизненный цикл платежа
Не ограничивайтесь одним успешным уведомлением. Проверьте возможные состояния и исключения: задержку платежа, недоплату, истечение срока, повторную доставку, неверные подписи, неизвестные значения track_id values, temporary database failure, and recovery after downtime.
Проверяйте и технический, и бизнес-результат. Эндпоинт может вернуть 200 OK while the wrong order is updated or the customer receives two confirmations. A complete test follows the event from OxaPay through your database, queue, customer message, fulfillment logic, and audit trail.
Используйте вебхуки вместе с проверками статуса
Вебхуки и запросы статуса через API решают разные части одной задачи. Вебхук дает быстрый сигнал. Запрос статуса обеспечивает авторитетный путь восстановления, если уведомление задержалось, не поступило, было обработано вне очереди или осталось неопределенным после локального сбоя.
| Метод | Оптимальное применение | Операционное ограничение |
|---|---|---|
| Уведомление вебхука | Быстрая реакция на изменение статуса платежа | Доставка может задерживаться, повторяться или временно быть недоступной |
| Запрос информации о платеже | Восстановление, сверка и подтверждение текущего состояния | Система должна определять момент запроса и избегать ненужного регулярного опроса |
For important payment flows, schedule reconciliation for records that remain pending too long or have not received an expected update. OxaPay’s Payment Information API can be used to retrieve the current payment details by the documented identifier.
Практические сценарии использования вебхуков
Заказы интернет-магазина
Пока платеж обрабатывается, держите заказ в ожидании. После проверки статуса завершения зарезервируйте или освободите товар по правилам бизнеса, однократно передайте заказ на исполнение и отправьте клиенту подтверждение.
SaaS и цифровой доступ
Активируйте учетную запись или продлевайте доступ только после подтвержденного результата платежа. Сохраняйте оплаченный период или изменение прав, чтобы повторный вызов не предоставил одно и то же преимущество дважды.
Финансы и сверка
Добавляйте платежные события в журнал аудита и связывайте их с внутренним счетом. Исключительные состояния можно направлять в очередь проверки, а плановые запросы статуса помогут сверять неразрешенные платежи.
Коммуникация с клиентами
Отправляйте сообщения по результату идемпотентного бизнес-процесса, а не непосредственно на каждый входящий вебхук. Это предотвращает дублирование писем и противоречивые сообщения при переходе платежа через несколько состояний.
Распространенные ошибки при работе с вебхуками
- Доверие странице возврата: use verified server-side payment information instead of a browser redirect.
- Проверка переформатированного JSON: calculate the HMAC from the original raw request body.
- Раскрытие ключа мерчанта: keep signing credentials in protected server-side storage.
- Предположение об уникальности каждого уведомления: make every business action idempotent.
- Слишком много операций до ответа: durably record the event, queue slow work, and respond promptly.
- Принятие любого перехода статуса: enforce a controlled payment state model.
- Опора только на доставку: use payment information requests for recovery and reconciliation.
- Запись чувствительных данных: retain useful identifiers and validation results without storing secrets unnecessarily.
Устранение неполадок вебхуков OxaPay
| Симптом | Что проверить |
|---|---|
| Уведомление не приходит | Проверьте URL обратного вызова, публичную доступность по HTTPS, правила межсетевого экрана, среду и журналы соответствующего платежа. |
| Не проходит проверка подписи | Используйте исходные байты запроса, правильный API-ключ мерчанта, документированный метод HMAC-SHA512 и точное сравнение. |
| Одно действие выполняется дважды | Проверьте ключ идемпотентности и убедитесь, что бизнес-действия регистрируются до возможного повторения. |
| Обратный вызов возвращает ошибку | Проверьте разбор запроса, доступность базы данных, состояние очереди, ошибки приложения и время ответа. |
| Локальный статус выглядит неверным | Запросите актуальную информацию о платеже, сравните идентификаторы и историю состояний, затем сверите локальную запись. |
Контрольный список запуска вебхуков OxaPay
- Рабочий URL обратного вызова использует HTTPS и доступен из публичного интернета.
- Исходное тело запроса сохраняется до завершения проверки HMAC-SHA512.
- API-ключ мерчанта надежно хранится и никогда не появляется в клиентском коде или журналах.
- Каждый обратный вызов сопоставляется с известным платежом и проверяется по ожидаемым бизнес-данным.
- Разрешенные переходы состояний платежа документированы и соблюдаются.
- Повторные уведомления не могут повторно запускать исполнение заказа, предоставление доступа, уведомления или бухгалтерские проводки.
- События и результаты проверки журналируются без лишних чувствительных данных.
- Задержанные или неопределенные платежи можно сверить через Payment Information API.
- Мониторинг предупреждает команду об ошибках подписи, обработки и росте очередей.
- Весь процесс протестирован до того, как от него стали зависеть реальные платежи клиентов.
Что дальше?
Сначала определите допустимое бизнес-действие для каждого статуса платежа. Затем создайте защищенный эндпоинт, который проверяет, сохраняет и устраняет дубли обратных вызовов перед запуском дальнейших операций. Наконец, добавьте механизм проверки статуса и сверки, чтобы временная ошибка доставки или системы не оставила заказ навсегда неразрешенным.
Более подробно о статусах платежей, доставке и архитектуре восстановления читайте в материале Мониторинг в реальном времени в блокчейн-платежных системах. Для разработчиков актуальная документация OxaPay по вебхукам as the implementation source of truth.
