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

Вебхук без сложных терминов

Сообщение от сервиса вашему серверу

Представьте, что проект создал операцию и ждёт результата. Вместо того чтобы каждую секунду спрашивать о статусе, он оставляет серверный адрес для уведомлений. Когда состояние меняется, сервис отправляет на этот адрес запрос.

Это техническое сообщение не предназначено для пользователя. Оно приходит на сервер проекта и содержит данные, необходимые для сопоставления события с операцией. Структуру сообщения нужно брать из документации DonPay.

Вебхук экономит лишние проверки, но не снимает ответственность за безопасность. Полученный запрос нельзя автоматически считать истинным только потому, что он пришёл на правильный URL.

Сценарий: оплата прошла — сервис получил уведомление

От ожидания к выполнению заказа

Проект создаёт внутренний заказ и платёжную операцию, затем переводит клиента по полученной ссылке. Пока подтверждения нет, заказ остаётся в состоянии ожидания.

После изменения статуса DonPay отправляет уведомление на указанный адрес. Сервер проекта принимает запрос, проверяет его подлинность и сопоставляет идентификатор с сохранённым заказом.

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

1. 1Создать и сохранить заказ.
2. 2Получить уведомление на сервер.
3. 3Проверить подлинность события.
4. 4Сопоставить идентификатор.
5. 5Применить изменение один раз.

Как сервис узнаёт об изменении статуса

Не путайте уведомление и действие пользователя

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

Сервер проекта ориентируется на проверенное событие и при необходимости запрашивает актуальное состояние предусмотренным способом. Это особенно важно, если сеть временно недоступна или уведомление обрабатывается с задержкой.

Храните внутренний идентификатор заказа отдельно от пользовательского текста. Так повторное событие можно безопасно сопоставить с уже обработанной записью.

• Не доверять параметрам адресной строки.
• Не считать возврат подтверждением.
• Проверять идентификатор и статус.
• Сохранять результат обработки.

Базовые правила безопасности

Проверка выполняется до изменения данных

Адрес вебхука доступен из сети, поэтому любой может попытаться отправить на него запрос. Обработчик должен проверить предусмотренную DonPay подпись или другой механизм подтверждения до выполнения любых действий.

Секрет для проверки хранится на сервере. Не выводите его в ответы, браузерный код и обычные журналы. Ошибочный запрос должен завершаться отказом без раскрытия внутренних деталей.

Валидируйте структуру входных данных, ограничивайте допустимые статусы и не доверяйте полям, которых нет в документации. Лишняя осторожность в обработчике защищает и деньги, и состояние заказов.

Почему событие нужно обрабатывать повторяемо

Один результат при нескольких доставках

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

Повторный вебхук не должен повторно выдавать продукт, увеличивать баланс заказа или создавать вторую запись. Сначала проверяйте текущее состояние и уникальный идентификатор, затем применяйте только допустимый переход.

Возвращайте успешный ответ после завершения обработки. Если внутри произошла временная ошибка, зафиксируйте её безопасно и предусмотрите повторную проверку статуса.

1. 1Принять запрос.
2. 2Проверить подпись и поля.
3. 3Найти операцию по идентификатору.
4. 4Убедиться, что событие ещё не применено.
5. 5Обновить состояние и ответить.

Как проверить интеграцию перед запуском

Проверьте успех, отказ и повтор

Составьте сценарии до написания обработчика. Минимально нужны ожидающая операция, успешное изменение, отклонённое событие, неверная подпись и повторная доставка.

Следите, чтобы тестовые действия не смешивались с реальными пользовательскими данными. Используйте доступный проекту безопасный порядок проверки и сверяйтесь с документацией.

После запуска контролируйте ошибки обработки и возможность вручную сопоставить заказ со статусом. Вебхук автоматизирует путь, но не отменяет наблюдаемость.