PM-1073 - trolley webhook handler

Author: vas3a

.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

prisma/migrations/20250416100509_add_trolley_webhook_log_table/migration.sql

@@ -0,0 +1,23 @@
+-- CreateEnum
+CREATE TYPE "webhook_status" AS ENUM ('error', 'processed', 'processing');
+
+-- CreateTable
+CREATE TABLE "trolley_webhook_log" (
+    "id" UUID NOT NULL DEFAULT uuid_generate_v4(),
+    "event_id" TEXT NOT NULL,
+    "event_time" TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "event_payload" TEXT NOT NULL,
+    "event_model" TEXT,
+    "event_action" TEXT,
+    "status" "webhook_status" NOT NULL,
+    "error_message" TEXT,
+    "created_by" VARCHAR(80),
+    "updated_by" VARCHAR(80),
+    "created_at" TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "trolley_webhook_log_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "trolley_webhook_log_event_id_key" ON "trolley_webhook_log"("event_id");

prisma/schema.prisma

@@ -1,7 +1,7 @@
 generator client {
-  provider = "prisma-client-js"
+  provider        = "prisma-client-js"
   previewFeatures = ["extendedIndexes"]
-  binaryTargets = ["native", "linux-musl-openssl-3.0.x"]
+  binaryTargets   = ["native", "linux-musl-openssl-3.0.x"]
 }
 
 datasource db {
@@ -210,6 +210,27 @@ model winnings {
   origin      origin?            @relation(fields: [origin_id], references: [origin_id], onDelete: NoAction, onUpdate: NoAction)
 }
 
+enum webhook_status {
+  error
+  processed
+  processing
+}
+
+model trolley_webhook_log {
+  id            String         @id @default(dbgenerated("uuid_generate_v4()")) @db.Uuid
+  event_id      String         @unique
+  event_time    DateTime       @default(now()) @db.Timestamp(6)
+  event_payload String
+  event_model   String?
+  event_action  String?
+  status        webhook_status
+  error_message String?
+  created_by    String?        @db.VarChar(80)
+  updated_by    String?        @db.VarChar(80)
+  created_at    DateTime?      @default(now()) @db.Timestamp(6)
+  updated_at    DateTime?      @default(now()) @db.Timestamp(6)
+}
+
 enum action_type {
   INITIATE_WITHDRAWAL
   ADD_WITHDRAWAL_METHOD

src/api/api.module.ts

@@ -15,9 +15,10 @@ import { TopcoderModule } from 'src/shared/topcoder/topcoder.module';
 import { OriginRepository } from './repository/origin.repo';
 import { TaxFormRepository } from './repository/taxForm.repo';
 import { PaymentMethodRepository } from './repository/paymentMethod.repo';
+import { WebhooksModule } from './webhooks/webhooks.module';
 
 @Module({
-  imports: [GlobalProvidersModule, TopcoderModule],
+  imports: [WebhooksModule, GlobalProvidersModule, TopcoderModule],
   controllers: [
     HealthCheckController,
     AdminWinningController,

src/api/webhooks/trolley-handlers/decorators.ts

@@ -0,0 +1,5 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const WEBHOOK_EVENT_METADATA_KEY = 'WH_EVENT_TYPE';
+export const WebhookEvent = (...events: string[]) =>
+  SetMetadata(WEBHOOK_EVENT_METADATA_KEY, events);

src/api/webhooks/trolley-handlers/index.ts

@@ -0,0 +1,61 @@
+import { Provider } from '@nestjs/common';
+import { PaymentHandler } from './payment.handler';
+import { TrolleyWebhookEvent } from '../webhooks.types';
+import { Reflector } from '@nestjs/core';
+import { WEBHOOK_EVENT_METADATA_KEY } from './decorators';
+
+/**
+ * Factory function to create a map of Trolley webhook event handlers.
+ *
+ * This function iterates over the provided handler classes and inspects their methods
+ * to find those annotated with specific metadata indicating the Trolley webhook events
+ * they handle. It then binds these methods to their respective event types and stores
+ * them in a map for easy lookup.
+ *
+ * @param reflector - An instance of `Reflector` used to retrieve metadata from methods.
+ * @param handlerClasses - An array of handler class instances containing methods
+ *                         annotated with Trolley webhook event metadata.
+ * @returns A `Map` where the keys are `TrolleyWebhookEvent` types and the values are
+ *          bound handler functions for those events.
+ */
+const trolleyHandlerFnsFactory = (reflector: Reflector, handlerClasses) => {
+  const handlersMap = new Map<TrolleyWebhookEvent, () => void>();
+
+  for (const handlerClass of handlerClasses) {
+    const prototype = Object.getPrototypeOf(handlerClass);
+    for (const propertyName of Object.getOwnPropertyNames(prototype)) {
+      const method = prototype[propertyName];
+      if (typeof method !== 'function' || propertyName === 'constructor') {
+        continue;
+      }
+
+      const eventTypes = reflector.get<TrolleyWebhookEvent[]>(
+        WEBHOOK_EVENT_METADATA_KEY,
+        method,
+      );
+
+      if (eventTypes?.length > 0) {
+        eventTypes.forEach((eventType) => {
+          handlersMap.set(eventType, method.bind(handlerClass));
+          console.log(`Found event handler: ${eventType} -> ${propertyName}`);
+        });
+      }
+    }
+  }
+
+  return handlersMap;
+};
+
+export const TrolleyWebhookHandlersProviders: Provider[] = [
+  PaymentHandler,
+  {
+    provide: 'TrolleyWebhookHandlers',
+    useFactory: (paymentHandler: PaymentHandler) => [paymentHandler],
+    inject: [PaymentHandler],
+  },
+  {
+    provide: 'trolleyHandlerFns',
+    useFactory: trolleyHandlerFnsFactory,
+    inject: [Reflector, 'TrolleyWebhookHandlers'],
+  },
+];

src/api/webhooks/trolley-handlers/payment.handler.ts

@@ -0,0 +1,19 @@
+import { Injectable } from '@nestjs/common';
+import { TrolleyWebhookEvent } from '../webhooks.types';
+import { WebhookEvent } from './decorators';
+
+@Injectable()
+export class PaymentHandler {
+  @WebhookEvent(TrolleyWebhookEvent.paymentCreated)
+  async handlePaymentCreated(payload: any): Promise<any> {
+    // TODO: Build out logic for payment.created event
+    console.log('handling', TrolleyWebhookEvent.paymentCreated);
+
+  }
+
+  @WebhookEvent(TrolleyWebhookEvent.paymentUpdated)
+  async handlePaymentUpdated(payload: any): Promise<any> {
+    // TODO: Build out logic for payment.updated event
+    console.log('handling', TrolleyWebhookEvent.paymentUpdated);
+  }
+}

src/api/webhooks/trolley.service.ts

@@ -0,0 +1,135 @@
+import crypto from 'crypto';
+import { Inject, Injectable } from '@nestjs/common';
+import { trolley_webhook_log, webhook_status } from '@prisma/client';
+import { PrismaService } from 'src/shared/global/prisma.service';
+
+enum TrolleyHeaders {
+  id = 'x-paymentrails-delivery',
+  signature = 'x-paymentrails-signature',
+  created = 'x-paymentrails-created',
+}
+
+const trolleyWhHmac = process.env.TROLLEY_WH_HMAC;
+if (!trolleyWhHmac) {
+  throw new Error('TROLLEY_WH_HMAC is not set!');
+}
+
+/**
+ * Service responsible for handling Trolley webhook operations.
+ */
+@Injectable()
+export class TrolleyService {
+  constructor(
+    @Inject('trolleyHandlerFns')
+    private readonly handlers,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  /**
+   * Validates the webhook signature to ensure the request is authentic.
+   *
+   * @param headers - The HTTP request headers containing the signature.
+   * @param bodyPayload - The raw body payload of the webhook request.
+   * @returns A boolean indicating whether the signature is valid.
+   */
+  validateSignature(headers: Request['headers'], bodyPayload: string): boolean {
+    if (!headers[TrolleyHeaders.signature]) {
+      return false;
+    }
+
+    const headerSignatureValues = (
+      headers[TrolleyHeaders.signature] ?? ''
+    ).split(',');
+
+    const t = headerSignatureValues[0].split('=')[1];
+    const v1 = headerSignatureValues[1].split('=')[1];
+
+    const hmac = crypto.createHmac('sha256', trolleyWhHmac as string);
+    hmac.update(`${t}${bodyPayload}`);
+    const digest = hmac.digest('hex');
+
+    return digest === v1;
+  }
+
+  /**
+   * Validates whether the webhook event is unique by checking its ID against the database.
+   *
+   * @param headers - The HTTP request headers containing the webhook ID.
+   * @returns A promise that resolves to a boolean indicating whether the webhook event is unique.
+   */
+  async validateUnique(headers: Request['headers']): Promise<boolean> {
+    const requestId = headers[TrolleyHeaders.id];
+    const whEvent = await this.prisma.trolley_webhook_log.findUnique({
+      where: { event_id: requestId },
+    });
+    return !whEvent;
+  }
+
+  /**
+   * Tracks the webhook events status by Updating or creating a record in the `trolley_webhook_log` table with the given event details.
+   *
+   * @param requestId - The unique identifier for the webhook event.
+   * @param status - The status of the webhook event.
+   * @param payload - (Optional) The payload associated with the webhook event.
+   * @param meta - (Optional) Additional metadata for the webhook event, such as event time.
+   * @returns A promise that resolves to the upserted `trolley_webhook_log` record.
+   */
+  setEventState(
+    requestId: string,
+    status: webhook_status,
+    payload?: any,
+    meta?: Partial<trolley_webhook_log>,
+  ) {
+    return this.prisma.trolley_webhook_log.upsert({
+      where: {
+        event_id: requestId,
+      },
+      create: {
+        event_id: requestId,
+        event_payload: JSON.stringify(payload ?? {}),
+        event_time: meta?.event_time,
+        event_model: payload?.model ?? '',
+        event_action: payload?.action ?? '',
+        status,
+        created_by: 'system',
+      } as trolley_webhook_log,
+      update: {
+        status,
+        ...meta,
+      },
+    });
+  }
+
+  /**
+   * Handles incoming webhook events by processing the payload and delegating
+   * the event to the appropriate handler based on the model and action.
+   *
+   * @param headers - The headers of the incoming request, containing metadata
+   * such as the event ID and creation time.
+   * @param payload - The body of the webhook event, containing details such as
+   * the model, action, and event-specific data.
+   */
+  async handleEvent(headers: Request['headers'], payload: any) {
+    const requestId = headers[TrolleyHeaders.id];
+
+    try {
+      await this.setEventState(requestId, webhook_status.processing, payload, {
+        event_time: headers[TrolleyHeaders.created],
+      });
+
+      const { model, action, body } = payload;
+      const handler = this.handlers.get(`${model}.${action}`);
+      if (!handler) {
+        throw new Error('Webhook event handler not found!');
+      }
+
+      await handler(body);
+      await this.setEventState(requestId, webhook_status.processed);
+    } catch (e) {
+      console.log(e);
+      await this.setEventState(requestId, webhook_status.error, void 0, {
+        error_message: e.message ?? e,
+      });
+    }
+  }
+}

src/api/webhooks/webhooks.controller.ts

@@ -0,0 +1,53 @@
+import {
+  Controller,
+  Post,
+  BadRequestException,
+  Req,
+  RawBodyRequest,
+  InternalServerErrorException,
+  ConflictException,
+} from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { TrolleyService } from './trolley.service';
+import { Public } from 'src/core/auth/decorators';
+
+@Public()
+@ApiTags('Webhooks')
+@Controller('webhooks')
+export class WebhooksController {
+  constructor(private readonly trolleyService: TrolleyService) {}
+
+  /**
+   * Handles incoming trolley webhooks.
+   *
+   * This method validates the webhook request by checking its signature and ensuring
+   * it has not been processed before. If validation passes, it processes the webhook
+   * payload and marks it as processed.
+   *
+   * @param request - The incoming webhook request containing headers, raw body, and parsed body.
+   * @returns A success message if the webhook is processed successfully.
+   * @throws {BadRequestException} If the signature is invalid or the webhook has already been processed.
+   */
+  @Post('trolley')
+  async handleTrolleyWebhook(@Req() request: RawBodyRequest<Request>) {
+    if (
+      !this.trolleyService.validateSignature(
+        request.headers,
+        request.rawBody?.toString('utf-8') ?? '',
+      )
+    ) {
+      throw new BadRequestException('Missing or invalid signature!');
+    }
+
+    if (!(await this.trolleyService.validateUnique(request.headers))) {
+      throw new ConflictException('Webhook already processed!');
+    }
+
+    try {
+      return this.trolleyService.handleEvent(request.headers, request.body);
+    } catch (e) {
+      console.log('Error processing the webhook!', e);
+      throw new InternalServerErrorException('Error processing the webhook!');
+    }
+  }
+}

src/api/webhooks/webhooks.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+import { TrolleyService } from './trolley.service';
+import { WebhooksController } from './webhooks.controller';
+import { TrolleyWebhookHandlersProviders } from './trolley-handlers';
+
+@Module({
+  imports: [],
+  controllers: [WebhooksController],
+  providers: [...TrolleyWebhookHandlersProviders, TrolleyService],
+})
+export class WebhooksModule {}

src/api/webhooks/webhooks.types.ts

@@ -0,0 +1,6 @@
+export enum TrolleyWebhookEvent {
+  paymentCreated = 'payment.created',
+  paymentUpdated = 'payment.updated',
+}
+
+export type TrolleyEventHandler = (eventPayload: any) => Promise<unknown>;

src/main.ts

@@ -7,7 +7,9 @@ import { ApiModule } from './api/api.module';
 import { AppModule } from './app.module';
 
 async function bootstrap() {
-  const app = await NestFactory.create<NestExpressApplication>(AppModule);
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    rawBody: true,
+  });
 
   // Global prefix for all routes is configured as `/v5/finance`
   app.setGlobalPrefix(process.env.API_BASE ?? '/v5/finance');