Защита webhook-уведомлений

Webhook-уведомления от YooKassa используются для асинхронного оповещения вашего сервера о событиях, таких как изменение статуса платежа или возврата.

Так как webhook - это публичный HTTP-эндпоинт, его обязательно необходимо защищать, чтобы исключить поддельные запросы и попытки атак.

Модуль nestjs-yookassa предоставляет готовое решение для защиты webhook-эндпоинтов.

Почему webhook нужно защищать

Без проверки подлинности злоумышленник может:

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

YooKassa официально рекомендует проверять подлинность webhook-уведомлений по IP-адресу отправителя и актуальному статусу объекта.

Как работает защита в nestjs-yookassa

В SDK реализован специальный Guard, который:

• проверяет IP-адрес запроса по официальному whitelist YooKassa;
• поддерживает IPv4, IPv6 и CIDR-диапазоны;
• корректно работает за Nginx, Cloudflare и другими прокси;
• блокирует любые запросы не от YooKassa с ошибкой 403 Forbidden.

Для удобства используется декларативный декоратор.

ВАЖНО: настройка trust proxy

Если ваше приложение работает за прокси-сервером (Nginx, Docker, Kubernetes, Cloudflare и т.д.), обязательно включите доверие к прокси.

Без этого NestJS не сможет корректно определить IP-адрес клиента, и все webhook-запросы будут отклоняться.

Пример настройки

async function bootstrap() {
	const app = await NestFactory.create(AppModule)

	// Обязательно для корректной работы IP-проверки webhook
	app.set('trust proxy', true)

	await app.listen(3000)
}

Использование декоратора YookassaWebhook

Для защиты эндпоинта достаточно добавить декоратор @YookassaWebhook().

import { Controller, Post, Body } from '@nestjs/common'
import { YookassaWebhook } from 'nestjs-yookassa'

@Controller('webhooks')
export class WebhooksController {
	@Post('yookassa')
	@YookassaWebhook()
	handleWebhook(@Body() event: any) {
		// event.object.status
		// event.object.id
	}
}

Декоратор автоматически:

• подключает Guard;
• проверяет IP-адрес отправителя;
• блокирует неавторизованные запросы.

Какие IP-адреса считаются доверенными

Используется официальный список IP-адресов YooKassa:

• 185.71.76.0/27
• 185.71.77.0/27
• 77.75.153.0/25
• 77.75.154.128/25
• 77.75.156.11
• 77.75.156.35
• 2a02:5180::/32

Рекомендуемые дополнительные проверки

Для максимальной безопасности YooKassa рекомендует:

• проверять актуальный статус объекта через API;
• не доверять данным webhook без серверной валидации;
• игнорировать повторные или устаревшие события.

Пример сценария:

1. Получили webhook
2. Проверили IP
3. Запросили объект через API YooKassa
4. Сравнили статус
5. Только после этого обновили данные в базе