Разработка API: Зачем нужен формат Webhooks и как реализовать прием уведомлений от платежной системы на своем сервере?
Webhooks — это механизм обратных вызовов (callback), при котором внешний сервис сам отправляет HTTP-запрос на ваш сервер при наступлении определённого события. В контексте платёжных систем это означает: как только пользователь оплатил заказ, платёжный шлюз (например, Stripe, ЮKassa, PayPal) немедленно отправляет POST-запрос на ваш эндпоинт с данными о транзакции.
**Зачем нужны Webhooks вместо polling?**
Альтернатива Webhooks — это polling: ваш сервер периодически опрашивает API платёжной системы («а есть ли новые платежи?»). Это неэффективно: создаёт лишнюю нагрузку, увеличивает задержку и расходует API-лимиты. Webhooks решают проблему реактивно — вы получаете уведомление мгновенно, без лишних запросов.
**Как реализовать прием Webhook-уведомлений?**
1. **Создайте эндпоинт на сервере.** Это обычный HTTP-маршрут, принимающий POST-запросы. Например, `/api/webhooks/payment`. Он должен быть доступен из интернета по HTTPS.
2. **Зарегистрируйте URL в личном кабинете платёжной системы.** Укажите адрес вашего эндпоинта в настройках интеграции.
3. **Верифицируйте подпись запроса.** Платёжные системы подписывают каждый Webhook секретным ключом (HMAC-SHA256). Обязательно проверяйте подпись в заголовке запроса, иначе злоумышленник сможет отправить поддельное уведомление об оплате.
python
import hmac, hashlib
def verify_signature(payload, signature, secret):
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
4. **Обработайте событие и верните ответ 200 OK.** Платёжная система ожидает ответ 200 в течение нескольких секунд. Если ответа нет — она повторит запрос. Поэтому тяжёлую логику (отправку email, обновление базы данных) лучше выносить в очередь задач (Celery, RabbitMQ, Redis Queue).
5. **Обеспечьте идемпотентность.** Один и тот же Webhook может прийти несколько раз. Сохраняйте идентификатор события и проверяйте, не обрабатывали ли вы его раньше.
6. **Логируйте все входящие запросы.** Сохраняйте тело запроса, заголовки и статус обработки — это критично для отладки и разрешения споров.
**Типичные ошибки:**
— Не проверять подпись (уязвимость безопасности).
— Возвращать 200 только после полной обработки (риск таймаута).
— Не обрабатывать повторные запросы (дублирование заказов).
Правильно реализованный Webhook-обработчик — основа надёжной платёжной интеграции.