feat(webhook): validate Heleket IP and signature (#44)

Author: TeaCoder52

src/api/payment/webhook/webhook.controller.ts

@@ -8,11 +8,16 @@ import {
 } from '@nestjs/common'
 import { ApiOkResponse, ApiOperation } from '@nestjs/swagger'
 
+import { HeleketService } from '@/libs/heleket/heleket.service'
+
 import { WebhookService } from './webhook.service'
 
 @Controller('webhook')
 export class WebhookController {
-	public constructor(private readonly webhookService: WebhookService) {}
+	public constructor(
+		private readonly webhookService: WebhookService,
+		private readonly heleketService: HeleketService
+	) {}
 
 	@ApiOperation({
 		summary: 'YooKassa Webhook',
@@ -34,10 +39,20 @@ export class WebhookController {
 		return { ok: true }
 	}
 
+	@ApiOperation({
+		summary: 'Heleket Webhook',
+		description: 'Endpoint to receive Heleket crypto payment events.'
+	})
+	@ApiOkResponse({
+		description: 'Webhook processed successfully',
+		schema: {
+			example: { ok: true }
+		}
+	})
 	@Post('crypto')
 	@HttpCode(HttpStatus.OK)
-	public async cryptoWebhook(@Body() payload: any) {
-		console.log(payload)
+	public async cryptoWebhook(@Body() payload: any, @Ip() ip: string) {
+		this.heleketService.verifyWebhook(ip, payload)
 
 		await this.webhookService.handleCrypto(payload)
 

src/api/payment/webhook/webhook.service.ts

@@ -72,13 +72,22 @@ export class WebhookService {
 	}
 
 	public async handleCrypto(payload: any) {
-		if (payload.status !== 'paid' || payload.status !== 'paid_over') return
-
-		await this.processPayment({
-			provider: 'crypto',
-			paymentId: payload.order_id,
-			paymentData: payload
-		})
+		if (payload.status === 'paid' || payload.status === 'paid_over') {
+			return await this.processPayment({
+				provider: 'crypto',
+				paymentId: payload.order_id,
+				paymentData: payload
+			})
+		} else if (payload.status === 'fail') {
+			return await this.prismaService.payment.update({
+				where: {
+					id: payload.order_id
+				},
+				data: {
+					status: PaymentStatus.FAILED
+				}
+			})
+		}
 	}
 
 	private async processPayment({

src/libs/heleket/enums/index.ts

@@ -0,0 +1 @@
+export * from './payment-status.enum'

src/libs/heleket/enums/payment-status.enum.ts

@@ -0,0 +1,15 @@
+/**
+ * Статусы платежей Heleket
+ */
+export enum HeleketPaymentStatus {
+	CONFIRM_CHECK = 'confirm_check',
+	PAID = 'paid',
+	PAID_OVER = 'paid_over',
+	FAIL = 'fail',
+	WRONG_AMOUNT = 'wrong_amount',
+	CANCEL = 'cancel',
+	SYSTEM_FAIL = 'system_fail',
+	REFUND_PROCESS = 'refund_process',
+	REFUND_FAIL = 'refund_fail',
+	REFUND_PAID = 'refund_paid'
+}

src/libs/heleket/heleket.service.ts

@@ -1,26 +1,29 @@
 import { HttpService } from '@nestjs/axios'
-import { Inject, Injectable } from '@nestjs/common'
-import { createHash } from 'crypto'
+import { BadRequestException, Inject, Injectable } from '@nestjs/common'
+import { createHash, timingSafeEqual } from 'crypto'
 import { firstValueFrom } from 'rxjs'
 
 import { type HeleketOptions, HeleketOptionsSymbol } from '@/common/interfaces'
 
 import type {
 	ApiResponse,
 	CreatePaymentRequest,
-	CreatePaymentResponse
+	CreatePaymentResponse,
+	HeleketPaymentWebhook
 } from './interfaces'
 
 @Injectable()
 export class HeleketService {
 	private readonly API_URL: string
+	private readonly TRUSTED_IPS: string[]
 
 	public constructor(
 		@Inject(HeleketOptionsSymbol)
 		private readonly options: HeleketOptions,
 		private readonly httpService: HttpService
 	) {
 		this.API_URL = 'https://api.heleket.com/v1'
+		this.TRUSTED_IPS = ['31.133.220.8']
 	}
 
 	public async createPayment(data: CreatePaymentRequest) {
@@ -32,6 +35,31 @@ export class HeleketService {
 		return response.result
 	}
 
+	public verifyWebhook(ip: string, payload: HeleketPaymentWebhook) {
+		if (!this.TRUSTED_IPS.includes(ip))
+			throw new BadRequestException('Invalid IP')
+
+		const { sign } = payload
+		const dataCopy = { ...payload }
+		delete dataCopy.sign
+
+		const jsonData = JSON.stringify(dataCopy).replace(/\//g, '\\/')
+
+		const base64Data = Buffer.from(jsonData, 'utf8').toString('base64')
+
+		const hash = createHash('md5')
+			.update(base64Data + this.options.apiKey, 'utf8')
+			.digest('hex')
+
+		if (
+			!timingSafeEqual(
+				Buffer.from(hash.toLowerCase(), 'utf8'),
+				Buffer.from(sign.toLowerCase(), 'utf8')
+			)
+		)
+			throw new BadRequestException('Invalid signature')
+	}
+
 	private async request<T = any>(
 		path: string,
 		body: any = {}

src/libs/heleket/interfaces/index.ts

@@ -1,2 +1,3 @@
 export * from './common.interface'
 export * from './create-payment.interface'
+export * from './webhook.interface'

src/libs/heleket/interfaces/webhook.interface.ts

@@ -0,0 +1,65 @@
+import { HeleketPaymentStatus } from '../enums'
+
+/**
+ * Информация о конвертации валюты для платежа
+ */
+export interface HeleketPaymentConvert {
+	/** Код валюты, в которую будет конвертирован платеж */
+	to_currency: string
+	/** Комиссия за конвертацию */
+	commission: string
+	/** Курс конверсии */
+	rate: string
+	/** Сумма конверсии в to_currency, которая была добавлена на баланс продавца с вычетом комиссии (merchant_amount * rate) */
+	amount: string
+}
+
+/**
+ * Payload webhook от Heleket
+ */
+export interface HeleketPaymentWebhook {
+	/** Тип счета */
+	type: 'payment'
+	/** UUID платежа */
+	uuid: string
+	/** Идентификатор заказа в вашей системе */
+	order_id: string
+	/** Сумма счета-фактуры */
+	amount: string
+	/** Сумма, фактически уплаченная клиентом (может быть null, если платеж ещё не совершен) */
+	payment_amount: string | null
+	/** Сумма в долларах США, фактически оплаченная клиентом */
+	payment_amount_usd?: string
+	/** Сумма, добавленная на баланс продавца с вычетом комиссии */
+	merchant_amount: string | null
+	/** Сумма комиссии Heleket */
+	commission?: string
+	/** Завершена ли счет-фактура */
+	is_final: boolean
+	/** Статус платежа */
+	status: HeleketPaymentStatus
+	/** Адрес кошелька плательщика */
+	from?: string | null
+	/** UUID статического кошелька */
+	wallet_address_uuid?: string | null
+	/** Сеть блокчейна */
+	network?: string
+	/** Валюта счета-фактуры */
+	currency: string
+	/** Валюта, которой клиент расплатился */
+	payer_currency: string
+	/** Сумма в валюте плательщика */
+	payer_amount: string
+	/** Курс обмена для payer_amount */
+	payer_amount_exchange_rate?: string
+	/** Дополнительная информация */
+	additional_data?: string | null
+	/** Идентификатор трансфера */
+	transfer_id?: string | null
+	/** Хэш транзакции в блокчейне */
+	txid?: string | null
+	/** Подпись webhook */
+	sign: string
+	/** Информация о конвертации валюты */
+	convert?: HeleketPaymentConvert
+}