BE-025: Implement Webhook Management Service

src/webhooks/dto/create-webhook.dto.ts

@@ -0,0 +1,83 @@
+import {
+  IsString,
+  IsUrl,
+  IsOptional,
+  IsArray,
+  IsBoolean,
+  IsNumber,
+  Min,
+  Max,
+  ArrayNotEmpty,
+} from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { WebhookEventType } from '../entities/webhook.entity';
+
+export class CreateWebhookDto {
+  @ApiProperty({
+    description: 'HTTPS endpoint URL that will receive webhook events',
+    example: 'https://api.example.com/webhooks/truthbounty',
+  })
+  @IsUrl({ protocols: ['https'], require_tld: false })
+  @IsString()
+  url: string;
+
+  @ApiPropertyOptional({
+    description: 'Human-readable description of this webhook',
+    example: 'Production analytics dashboard',
+  })
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiProperty({
+    description: 'Blockchain wallet address that owns this webhook',
+    example: '0x1234567890abcdef1234567890abcdef12345678',
+  })
+  @IsString()
+  ownerId: string;
+
+  @ApiPropertyOptional({
+    description: 'Whether the webhook is active (default: true)',
+    default: true,
+  })
+  @IsOptional()
+  @IsBoolean()
+  enabled?: boolean;
+
+  @ApiProperty({
+    description: 'Event types to subscribe to',
+    example: ['claim.created', 'verification.completed', 'reward.distributed'],
+    enum: WebhookEventType,
+    isArray: true,
+  })
+  @IsArray()
+  @ArrayNotEmpty()
+  @IsString({ each: true })
+  events: WebhookEventType[];
+
+  @ApiPropertyOptional({
+    description: 'Optional JSON filters for event payload filtering',
+    example: { network: 'mainnet', severity: 'high' },
+  })
+  @IsOptional()
+  filters?: Record<string, any>;
+
+  @ApiPropertyOptional({
+    description: 'Maximum number of retry attempts for failed deliveries (default: 3)',
+    default: 3,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(10)
+  maxRetries?: number;
+
+  @ApiPropertyOptional({
+    description: 'Base retry interval in milliseconds (default: 30000)',
+    default: 30000,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(1000)
+  retryIntervalMs?: number;
+}

src/webhooks/dto/update-webhook.dto.ts

@@ -0,0 +1,72 @@
+import {
+  IsString,
+  IsUrl,
+  IsOptional,
+  IsArray,
+  IsBoolean,
+  IsNumber,
+  Min,
+  Max,
+} from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { WebhookEventType } from '../entities/webhook.entity';
+
+export class UpdateWebhookDto {
+  @ApiPropertyOptional({
+    description: 'HTTPS endpoint URL that will receive webhook events',
+    example: 'https://api.example.com/webhooks/truthbounty',
+  })
+  @IsOptional()
+  @IsUrl({ protocols: ['https'], require_tld: false })
+  @IsString()
+  url?: string;
+
+  @ApiPropertyOptional({
+    description: 'Human-readable description of this webhook',
+  })
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiPropertyOptional({
+    description: 'Whether the webhook is active',
+  })
+  @IsOptional()
+  @IsBoolean()
+  enabled?: boolean;
+
+  @ApiPropertyOptional({
+    description: 'Event types to subscribe to',
+    enum: WebhookEventType,
+    isArray: true,
+  })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  events?: WebhookEventType[];
+
+  @ApiPropertyOptional({
+    description: 'Optional JSON filters for event payload filtering',
+  })
+  @IsOptional()
+  filters?: Record<string, any>;
+
+  @ApiPropertyOptional({
+    description: 'Maximum number of retry attempts for failed deliveries',
+    default: 3,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Max(10)
+  maxRetries?: number;
+
+  @ApiPropertyOptional({
+    description: 'Base retry interval in milliseconds',
+    default: 30000,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(1000)
+  retryIntervalMs?: number;
+}

src/webhooks/dto/webhook-filter.dto.ts

@@ -0,0 +1,55 @@
+import { IsOptional, IsString, IsEnum, IsNumber, Min } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { DeliveryStatus } from '../entities/webhook-delivery.entity';
+
+export class WebhookDeliveryFilterDto {
+  @ApiPropertyOptional({
+    description: 'Filter by event type',
+    example: 'claim.created',
+  })
+  @IsOptional()
+  @IsString()
+  eventType?: string;
+
+  @ApiPropertyOptional({
+    description: 'Filter by delivery status',
+    enum: DeliveryStatus,
+  })
+  @IsOptional()
+  @IsEnum(DeliveryStatus)
+  status?: DeliveryStatus;
+
+  @ApiPropertyOptional({
+    description: 'Page number (1-based)',
+    default: 1,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(1)
+  page?: number;
+
+  @ApiPropertyOptional({
+    description: 'Items per page',
+    default: 20,
+  })
+  @IsOptional()
+  @IsNumber()
+  @Min(1)
+  limit?: number;
+}
+
+export class WebhookListFilterDto {
+  @ApiPropertyOptional({
+    description: 'Filter by enabled/disabled status',
+  })
+  @IsOptional()
+  @IsString()
+  enabled?: string;
+
+  @ApiPropertyOptional({
+    description: 'Filter by owner wallet address',
+  })
+  @IsOptional()
+  @IsString()
+  ownerId?: string;
+}

src/webhooks/entities/webhook-delivery.entity.ts

@@ -0,0 +1,79 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  Index,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
+import { Webhook } from './webhook.entity';
+
+export enum DeliveryStatus {
+  PENDING = 'PENDING',
+  DELIVERED = 'DELIVERED',
+  FAILED = 'FAILED',
+  DEAD_LETTER = 'DEAD_LETTER',
+}
+
+@Entity('webhook_deliveries')
+@Index(['webhookId'])
+@Index(['status'])
+@Index(['createdAt'])
+@Index(['webhookId', 'status'])
+export class WebhookDelivery {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  webhookId: string;
+
+  @ManyToOne(() => Webhook, (webhook) => webhook.deliveries, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'webhookId' })
+  webhook: Webhook;
+
+  @Column()
+  eventType: string;
+
+  @Column({ type: 'json' })
+  payload: Record<string, any>;
+
+  @Column({ type: 'varchar', default: DeliveryStatus.PENDING })
+  status: DeliveryStatus;
+
+  @Column({ nullable: true })
+  responseStatus: number;
+
+  @Column({ type: 'text', nullable: true })
+  responseBody: string;
+
+  @Column({ nullable: true })
+  latency: number;
+
+  @Column({ default: 0 })
+  retryCount: number;
+
+  @Column()
+  maxRetries: number;
+
+  @Column({ type: 'text', nullable: true })
+  failureReason: string | null;
+
+  @Column()
+  requestId: string;
+
+  @Column()
+  nonce: string;
+
+  @Column()
+  signature: string;
+
+  @Column()
+  timestamp: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @Column({ type: 'datetime', nullable: true })
+  completedAt: Date | null;
+}

src/webhooks/entities/webhook-subscription.entity.ts

@@ -0,0 +1,35 @@
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  Index,
+  ManyToOne,
+  JoinColumn,
+} from 'typeorm';
+import { Webhook } from './webhook.entity';
+
+@Entity('webhook_subscriptions')
+@Index(['webhookId'])
+@Index(['eventType'])
+@Index(['webhookId', 'eventType'], { unique: true })
+export class WebhookSubscription {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  webhookId: string;
+
+  @ManyToOne(() => Webhook, (webhook) => webhook.subscriptions, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'webhookId' })
+  webhook: Webhook;
+
+  @Column()
+  eventType: string;
+
+  @Column({ type: 'json', nullable: true })
+  filters: Record<string, any> | null;
+
+  @CreateDateColumn()
+  createdAt: Date;
+}