Вебхук оплаты: что это, как проверить подпись и не выдать товар дважды

Что такое вебхук оплаты и зачем он нужен

Вебхук (webhook, callback оплаты) — это обратный вызов: когда платёж оплачен, отклонён или возвращён, платёжный шлюз отправляет POST-запрос на адрес, который вы указали в настройках проекта. В теле запроса обычно приходит идентификатор платежа, ваш номер заказа, статус, сумма и валюта.

Без вебхука вам пришлось бы постоянно опрашивать API: «оплачен ли заказ 1042?». Это лишняя нагрузка и задержка. Вебхук работает наоборот: вы получаете уведомление об оплате в момент события и сразу выдаёте ключ, доступ, файл или сообщение в Telegram-боте.

Если вы продаёте цифровые товары и подписки, вебхук — основа автовыдачи. Общую картину по этой теме мы разбирали в блоге, а здесь сосредоточимся на технике: что именно писать в обработчике.

Чем вебхук лучше страницы «Спасибо» после оплаты

Новички часто выдают товар, когда покупатель вернулся на страницу успеха. Это ненадёжно: человек может закрыть вкладку, потерять связь или просто не дождаться редиректа. А ещё адрес страницы успеха можно открыть вручную без всякой оплаты.

Как устроен вебхук: что приходит и что нужно ответить

Состав запроса

Точные названия полей и событий смотрите в документации по вебхукам. По смыслу в уведомлении всегда есть несколько обязательных вещей:

• идентификатор платежа на стороне шлюза — по нему вы отличаете события друг от друга;
• ваш внутренний номер заказа, который вы передали при создании платежа;
• статус: оплачен, ожидает, отклонён, возвращён;
• сумма и валюта — их нужно сверять с заказом;
• подпись, по которой вы убеждаетесь, что запрос отправил именно шлюз.

Ответ вашего сервера

Код ответа 2xx сообщает шлюзу: «уведомление получено и обработано». Любой другой код или таймаут — сигнал, что доставку нужно повторить. Поэтому отвечайте успехом только тогда, когда результат уже сохранён у вас в базе.

Подпись вебхука: как проверить, что запрос настоящий

Адрес вашего обработчика не секрет, и любой может отправить на него поддельный POST «заказ оплачен». Подпись решает эту проблему. Обычно это хеш (чаще всего HMAC) от тела запроса, посчитанный с секретным ключом, который знаете только вы и платёжная система. Paydex отправляет подписанные вебхуки; алгоритм и название заголовка уточняйте в документации.

Принцип проверки одинаков в Node.js, PHP и Python, для которых у Paydex есть SDK:

1. Прочитайте сырое тело запроса как есть, до разбора JSON. Если пересериализовать объект, порядок полей или пробелы изменятся и подпись не сойдётся.
2. Посчитайте подпись тем же алгоритмом с вашим секретным ключом из кабинета.
3. Сравните результат с присланной подписью функцией сравнения за постоянное время (timing-safe), а не обычным оператором равенства.
4. Если подпись не совпала — верните 401 и не трогайте заказ.

Идемпотентность и повторы: почему вебхук придёт дважды

Доставка вебхука устроена по принципу «минимум один раз». Если ваш сервер не ответил вовремя или вернул ошибку, шлюз отправит то же уведомление снова. Бывает и так, что вы успели обработать запрос, но ответ потерялся по пути, и повтор приходит уже после выдачи товара.

Отсюда главное правило: обработчик должен быть идемпотентным — повторная обработка того же события не меняет результат. Покупатель не должен получить два ключа или две подписки за один платёж.

Два способа защититься от дублей

• Проверка статуса заказа. Если заказ уже помечен оплаченным — просто верните 200.
• Таблица обработанных событий. Сохраняйте идентификатор платежа или события с уникальным индексом. Попытка вставить дубль завершится ошибкой базы — это и есть сигнал «уже обработано».

Надёжнее использовать оба способа сразу и выполнять их внутри одной транзакции. Тогда два параллельных запроса с одним платежом не пройдут проверку одновременно.

Пример логики автовыдачи товара после оплаты

Ниже — независимый от языка алгоритм обработчика. Его можно реализовать на любом стеке, а в SDK Paydex уже есть вспомогательные функции для проверки подписи.

1. Получите сырое тело запроса и заголовок с подписью.
2. Проверьте подпись. Не совпала — ответ 401, конец обработки.
3. Разберите JSON и достаньте идентификатор платежа, номер заказа, статус, сумму и валюту.
4. Если статус не «оплачен» (например, ожидание или отклонение) — обновите заказ при необходимости, ответьте 200 и завершите.
5. Откройте транзакцию и заблокируйте строку заказа. Если заказ уже оплачен — ответьте 200 без повторной выдачи.
6. Сверьте сумму и валюту платежа с заказом. При расхождении не выдавайте товар автоматически, а отметьте заказ для ручной проверки.
7. Пометьте заказ оплаченным и запишите идентификатор платежа в таблицу обработанных событий с уникальным индексом.
8. Поставьте задачу выдачи в очередь: отправить ключ на почту, открыть доступ, написать покупателю в Telegram-боте.
9. Зафиксируйте транзакцию и верните 200 как можно быстрее.

Обратите внимание на пункт 8: тяжёлые операции (письма, генерация файлов, обращения к внешним сервисам) лучше делать в фоне. Обработчик, который отвечает за секунды, провоцирует таймауты и ненужные повторы.

Что делать с возвратами

Если покупателю вернули деньги, уведомление об этом тоже придёт как событие. Заведите для него отдельную ветку: отзовите доступ или ключ, обновите статус заказа. Сами возвраты можно оформлять через кабинет и API — подробности в разделе про возвраты через API.

Как протестировать вебхуки и запустить приём оплат с Paydex за день

Отлаживать обработчик на реальных деньгах не нужно. В Paydex есть тестовый режим, в котором можно проводить платежи и получать вебхуки без настоящих списаний; порядок работы описан на странице про тестирование. Для локальной разработки пригодится любой туннель, который пробрасывает публичный HTTPS-адрес на ваш компьютер.

Проверьте минимум пять сценариев:

• успешная оплата — товар выдан один раз;
• повторная доставка того же события — второй выдачи нет;
• неверная подпись — запрос отклонён с 401;
• ошибка на вашей стороне (5xx) — после исправления уведомление доходит повторно;
• возврат — доступ отзывается.

Путь от регистрации до первых оплат

Подключить Paydex можно за день: регистрация, создание проекта (сайт или Telegram-бот), подтверждение домена или бота, модерация (обычно до суток) и получение ключей API. ИП и ООО для этого не нужны — Paydex работает с обычными физическими лицами. Принимать можно СБП, карты РФ и USDT (TRC20, BEP20), а выводить — в USDT или в рублях на карту и по СБП. Пошаговая инструкция есть в быстром старте.

Частые ошибки при работе с вебхуками

• Выдача по редиректу. Покупатель может не вернуться на сайт, а адрес страницы успеха легко открыть вручную.
• Нет проверки подписи. Любой, кто знает адрес обработчика, сможет «оплатить» заказ бесплатно.
• Разбор JSON до проверки подписи. Подпись считается от исходных байтов тела запроса.
• Ответ 200 до записи в базу. При сбое вы потеряете событие, а шлюз уже не повторит доставку.
• Нет защиты от дублей. Повтор уведомления приводит к двойной выдаче ключей.
• Тяжёлая работа внутри обработчика. Он не успевает ответить, и шлюз присылает повторы.
• Не сверяются сумма и валюта. Заказ на одну сумму не должен закрываться платежом на другую.
• Нет логов. Сохраняйте идентификатор платежа, результат проверки подписи и принятое решение — разбор спорных заказов займёт минуты, а не часы.

Если что-то не сходится, сначала посмотрите, какие вебхуки шлюз отправлял и какие ответы получал, затем сравните с вашими логами. С вопросами можно обратиться в поддержку Paydex в Telegram.

Итоги: чек-лист надёжного вебхука оплаты

1. Выдавайте товар только по вебхуку, а не по возврату покупателя на сайт.
2. Проверяйте подпись по сырому телу запроса и секретному ключу.
3. Сделайте обработчик идемпотентным: статус заказа плюс уникальный индекс на идентификатор платежа.
4. Сверяйте сумму и валюту, обрабатывайте возвраты отдельной веткой.
5. Отвечайте 2xx только после сохранения результата, а тяжёлые задачи уносите в очередь.
6. Отладьте все сценарии в тестовом режиме, затем переходите на боевые платежи.

Размер комиссии зависит от оборота и тематики проекта, актуальные условия смотрите на странице тарифов. Вебхуки, REST API и SDK доступны без отдельной оплаты за подключение.