webhook криптоплатежа: как обрабатывать id и status
Гайд по webhook криптоплатежа: получайте финальный статус методом POST с id и status, проверяйте заголовок x-api-key и безопасно обновляйте заказы.
webhook криптоплатежа сообщает вашему бэкенду финальный статус платежа. В Qvard это POST с номером вашего заказа и статусом, поэтому логика заказа обновляется без опроса API.
Что отправляет webhook
Qvard вызывает ваш webhook-URL запросом POST. В теле находится id, который вы передали при создании платежа, и статус, например paid. Запрос несёт ваш токен x-api-key в заголовке.
Проверка заголовка x-api-key
Прежде чем доверять сообщению, сравните заголовок x-api-key с токеном из вашего аккаунта. Отклоняйте запросы без него, чтобы никто не мог пометить заказ оплаченным, просто вызвав ваш endpoint.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Обновление заказа по id
Найдите заказ по id из тела и измените его состояние по статусу. Помечайте заказ оплаченным только при статусе paid и игнорируйте статусы, которые ваша система не обрабатывает.
Повторный вызов не должен ломать заказ
Один и тот же webhook может прийти несколько раз. Сохраняйте обработанные id и статус и ничего не делайте, если событие уже обработано. Отвечайте кодом успеха после сохранения изменений.
Быстрый ответ и очередь для тяжёлой работы
Подтверждайте webhook сразу после сохранения заказа. Письма, счета и вызовы склада отправляйте из фоновой задачи, чтобы медленный шаг никогда не вызывал таймаут.
Проверка на тестовом платеже
Создайте тестовый платёж, оплатите его на платёжной странице и убедитесь, что ваш endpoint получает webhook, прежде чем выходить в продакшен.
FAQ
В чём разница между ответом API и webhook?
Ответ API подтверждает, что платёж создан, и возвращает redirectUrl. Только webhook сообщает финальный статус платежа.
Что будет, если мой endpoint недоступен?
Доставка повторяется, поэтому обработчик должен быть безопасен при повторном вызове. Регулярно проверяйте логи и сверяйте заказы, которые остались в ожидании.
Можно ли доверять webhook без x-api-key?
Нет. Всегда проверяйте заголовок x-api-key перед изменением заказа.
Какие статусы нужно обрабатывать?
Для успешных платежей обрабатывайте paid, а остальные статусы воспринимайте как информацию. Полный набор значений приведён в документации API.
