Add NGO webhook delivery system

app/backend/prisma/migrations/20260328000000_add_webhook_subscriptions/migration.sql

@@ -0,0 +1,40 @@
+CREATE TABLE "WebhookSubscription" (
+    "id" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "apiKeyId" TEXT NOT NULL,
+    "url" TEXT NOT NULL,
+    "secret" TEXT NOT NULL,
+    "events" TEXT[] NOT NULL,
+    "isActive" BOOLEAN NOT NULL DEFAULT true,
+
+    CONSTRAINT "WebhookSubscription_pkey" PRIMARY KEY ("id")
+);
+
+CREATE TABLE "WebhookDeliveryAttempt" (
+    "id" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "subscriptionId" TEXT NOT NULL,
+    "event" TEXT NOT NULL,
+    "attempt" INTEGER NOT NULL,
+    "status" TEXT NOT NULL,
+    "payload" JSONB NOT NULL,
+    "responseStatus" INTEGER,
+    "responseBody" TEXT,
+    "errorMessage" TEXT,
+    "deliveredAt" TIMESTAMP(3),
+
+    CONSTRAINT "WebhookDeliveryAttempt_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX "WebhookSubscription_apiKeyId_idx" ON "WebhookSubscription"("apiKeyId");
+CREATE INDEX "WebhookSubscription_isActive_idx" ON "WebhookSubscription"("isActive");
+CREATE INDEX "WebhookDeliveryAttempt_subscriptionId_createdAt_idx" ON "WebhookDeliveryAttempt"("subscriptionId", "createdAt");
+CREATE INDEX "WebhookDeliveryAttempt_event_status_idx" ON "WebhookDeliveryAttempt"("event", "status");
+
+ALTER TABLE "WebhookSubscription" ADD CONSTRAINT "WebhookSubscription_apiKeyId_fkey"
+FOREIGN KEY ("apiKeyId") REFERENCES "ApiKey"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "WebhookDeliveryAttempt" ADD CONSTRAINT "WebhookDeliveryAttempt_subscriptionId_fkey"
+FOREIGN KEY ("subscriptionId") REFERENCES "WebhookSubscription"("id") ON DELETE CASCADE ON UPDATE CASCADE;

app/backend/prisma/schema.prisma

@@ -88,6 +88,46 @@ model Claim {
   @@index([deletedAt])
 }
 
+model WebhookSubscription {
+  id        String   @id @default(cuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  apiKeyId  String
+  apiKey    ApiKey   @relation(fields: [apiKeyId], references: [id], onDelete: Cascade)
+
+  url       String
+  secret    String
+  events    String[]
+  isActive  Boolean  @default(true)
+
+  deliveries WebhookDeliveryAttempt[]
+
+  @@index([apiKeyId])
+  @@index([isActive])
+}
+
+model WebhookDeliveryAttempt {
+  id             String               @id @default(cuid())
+  createdAt      DateTime             @default(now())
+  updatedAt      DateTime             @updatedAt
+
+  subscriptionId String
+  subscription   WebhookSubscription  @relation(fields: [subscriptionId], references: [id], onDelete: Cascade)
+
+  event          String
+  attempt        Int
+  status         String
+  payload        Json
+  responseStatus Int?
+  responseBody   String?
+  errorMessage   String?
+  deliveredAt    DateTime?
+
+  @@index([subscriptionId, createdAt])
+  @@index([event, status])
+}
+
 model AuditLog {
   id        String   @id @default(cuid())
   actorId   String
@@ -149,5 +189,5 @@ model ApiKey {
   createdAt   DateTime @default(now())
   updatedAt   DateTime @updatedAt
 
-  @@index([ngoId])
+  webhookSubscriptions WebhookSubscription[]
 }

app/backend/src/app.module.ts

@@ -31,7 +31,7 @@ import { LoggingInterceptor } from './interceptors/logging.interceptor';
 import { LoggerService } from './logger/logger.service';
 import { AllExceptionsFilter } from './common/filters/http-exception.filter';
 import { AnalyticsModule } from './analytics/analytics.module';
-import { AidEscrowModule } from './onchain/aid-escrow.module';
+import { WebhooksModule } from './webhooks/webhooks.module';
 
 @Module({
   imports: [
@@ -74,7 +74,7 @@ import { AidEscrowModule } from './onchain/aid-escrow.module';
     NotificationsModule,
     JobsModule,
     AnalyticsModule,
-    AidEscrowModule,
+    WebhooksModule,
   ],
 
   controllers: [AppController],

app/backend/src/campaigns/campaigns.controller.ts

@@ -54,7 +54,7 @@
     description: 'Access denied - insufficient permissions for this operation.',
   })
   async create(@Body() dto: CreateCampaignDto, @Req() req: Request) {
     const campaign = await this.campaigns.create(dto, req.user?.ngoId);
     return ApiResponseDto.ok(campaign, 'Campaigns created successfully');
   }
 
@@ -74,8 +74,8 @@
     @Req() req: Request,
   ) {
     // Scope to ngoId for NGO role; admins/operators see all
     const ngoId = req.user?.role === AppRole.ngo ? req.user.ngoId : undefined;
     const campaigns = await this.campaigns.findAll(includeArchived, ngoId);
     return ApiResponseDto.ok(campaigns, 'Campaigns fetched successfully');
   }
 
@@ -132,6 +132,7 @@
   @ApiForbiddenResponse({
     description: 'Access denied - insufficient permissions.',
   })
+  @Patch(':id/archive')
   async archive(@Param('id') id: string) {
     const campaignData = await this.campaigns.archive(id);
     const { campaign, alreadyArchived } = campaignData;

app/backend/src/campaigns/campaigns.module.ts

@@ -1,8 +1,11 @@
 import { Module } from '@nestjs/common';
 import { CampaignsController } from './campaigns.controller';
 import { CampaignsService } from './campaigns.service';
+import { PrismaModule } from '../prisma/prisma.module';
+import { WebhooksModule } from '../webhooks/webhooks.module';
 
 @Module({
+  imports: [PrismaModule, WebhooksModule],
   controllers: [CampaignsController],
   providers: [CampaignsService],
 })

app/backend/src/campaigns/campaigns.service.spec.ts

@@ -4,10 +4,14 @@ import { Campaign, CampaignStatus, Prisma } from '@prisma/client';
 import { CampaignsService } from './campaigns.service';
 import { PrismaService } from 'src/prisma/prisma.service';
 import { DeepMockProxy, mockDeep } from 'jest-mock-extended';
+import { WebhooksService } from '../webhooks/webhooks.service';
 
 describe('CampaignsService', () => {
   let service: CampaignsService;
   let prismaMock: DeepMockProxy<PrismaService>;
+  const webhooksService = {
+    enqueueEvent: jest.fn().mockResolvedValue(1),
+  };
 
   const now = new Date('2026-01-25T00:00:00.000Z');
 
@@ -32,6 +36,7 @@ describe('CampaignsService', () => {
       providers: [
         CampaignsService,
         { provide: PrismaService, useValue: prismaMock },
+        { provide: WebhooksService, useValue: webhooksService },
       ],
     }).compile();
 
@@ -156,4 +161,39 @@ describe('CampaignsService', () => {
     expect(updateArgs?.data).toMatchObject({ deletedAt: expect.any(Date) });
     expect(result.deletedAt).not.toBeNull();
   });
+
+  it('update(): emits campaign.completed when status transitions to completed', async () => {
+    const existing: Campaign = {
+      id: 'c1',
+      name: 'A',
+      status: CampaignStatus.active,
+      budget: new Prisma.Decimal('10.00'),
+      metadata: null,
+      archivedAt: null,
+      createdAt: now,
+      updatedAt: now,
+    };
+    const updated: Campaign = {
+      ...existing,
+      status: CampaignStatus.completed,
+      updatedAt: new Date('2026-01-26T00:00:00.000Z'),
+    };
+
+    prismaMock.campaign.findUnique.mockResolvedValue(existing);
+    prismaMock.campaign.update.mockResolvedValue(updated);
+
+    await service.update('c1', { status: CampaignStatus.completed });
+
+    expect(webhooksService.enqueueEvent).toHaveBeenCalledWith(
+      'campaign.completed',
+      expect.objectContaining({
+        event: 'campaign.completed',
+        campaign: expect.objectContaining({
+          id: 'c1',
+          status: CampaignStatus.completed,
+        }),
+        previousStatus: CampaignStatus.active,
+      }),
+    );
+  });
 });

app/backend/src/campaigns/campaigns.service.ts

@@ -3,10 +3,14 @@ import { CampaignStatus, Prisma } from '@prisma/client';
 import { PrismaService } from '../prisma/prisma.service';
 import { CreateCampaignDto } from './dto/create-campaign.dto';
 import { UpdateCampaignDto } from './dto/update-campaign.dto';
+import { WebhooksService } from '../webhooks/webhooks.service';
 
 @Injectable()
 export class CampaignsService {
-  constructor(private readonly prisma: PrismaService) {}
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly webhooksService: WebhooksService,
+  ) {}
 
   private sanitizeMetadata(
     metadata?: Record<string, unknown>,
@@ -51,9 +55,9 @@ export class CampaignsService {
   }
 
   async update(id: string, dto: UpdateCampaignDto) {
-    await this.findOne(id);
+    const existing = await this.findOne(id);
 
-    return this.prisma.campaign.update({
+    const updated = await this.prisma.campaign.update({
       where: { id },
       data: {
         name: dto.name,
@@ -65,6 +69,26 @@ export class CampaignsService {
             : this.sanitizeMetadata(dto.metadata),
       },
     });
+
+    if (
+      updated.status === CampaignStatus.completed &&
+      existing.status !== CampaignStatus.completed
+    ) {
+      await this.webhooksService.enqueueEvent('campaign.completed', {
+        event: 'campaign.completed',
+        occurredAt: updated.updatedAt.toISOString(),
+        campaign: {
+          id: updated.id,
+          name: updated.name,
+          status: updated.status,
+          budget: updated.budget.toString(),
+          archivedAt: updated.archivedAt?.toISOString() ?? null,
+        },
+        previousStatus: existing.status,
+      });
+    }
+
+    return updated;
   }
 
   async archive(id: string) {

app/backend/src/claims/claims.module.ts

@@ -6,6 +6,7 @@ import { OnchainModule } from '../onchain/onchain.module';
 import { MetricsModule } from '../observability/metrics/metrics.module';
 import { LoggerModule } from '../logger/logger.module';
 import { AuditModule } from '../audit/audit.module';
+import { WebhooksModule } from '../webhooks/webhooks.module';
 import { EncryptionModule } from '../common/encryption/encryption.module';
 
 @Module({
@@ -15,6 +16,7 @@ import { EncryptionModule } from '../common/encryption/encryption.module';
     MetricsModule,
     LoggerModule,
     AuditModule,
+    WebhooksModule,
     EncryptionModule,
   ],
   controllers: [ClaimsController],

app/backend/src/claims/claims.service.spec.ts

@@ -13,6 +13,7 @@ import { MetricsService } from '../observability/metrics/metrics.service';
 import { AuditService } from '../audit/audit.service';
 import { EncryptionService } from '../common/encryption/encryption.service';
 import { ClaimStatus, Prisma } from '@prisma/client';
+import { WebhooksService } from '../webhooks/webhooks.service';
 
 describe('ClaimsService', () => {
   let service: ClaimsService;
@@ -63,6 +64,10 @@ describe('ClaimsService', () => {
     record: jest.fn().mockResolvedValue({ id: 'audit-1' }),
   };
 
+  const mockWebhooksService = {
+    enqueueEvent: jest.fn().mockResolvedValue(1),
+  };
+
   beforeEach(async () => {
     const module: TestingModule = await Test.createTestingModule({
       providers: [
@@ -121,6 +126,10 @@ describe('ClaimsService', () => {
             decryptDeterministic: jest.fn((v: string) => v),
           },
         },
+        {
+          provide: WebhooksService,
+          useValue: mockWebhooksService,
+        },
       ],
     }).compile();
 
@@ -134,6 +143,39 @@ describe('ClaimsService', () => {
     jest.clearAllMocks();
   });
 
+  it('verify should enqueue claim.verified webhooks after a successful transition', async () => {
+    jest.spyOn(prismaService.claim, 'findUnique').mockResolvedValueOnce({
+      ...mockClaim,
+      status: ClaimStatus.requested,
+    } as typeof mockClaim);
+    type TxClient = { claim: { update: jest.Mock } };
+    jest
+      .spyOn(prismaService, '$transaction')
+      .mockImplementation(
+        async (callback: (tx: TxClient) => Promise<unknown>) =>
+          callback({
+            claim: {
+              update: jest.fn().mockResolvedValue({
+                ...mockClaim,
+                status: ClaimStatus.verified,
+              }),
+            },
+          }),
+      );
+
+    await service.verify('claim-123');
+
+    expect(mockWebhooksService.enqueueEvent).toHaveBeenCalledWith(
+      'claim.verified',
+      expect.objectContaining({
+        event: 'claim.verified',
+        claim: expect.objectContaining({
+          id: 'claim-123',
+        }),
+      }),
+    );
+  });
+
   describe('disburse', () => {
     it('should call on-chain adapter when enabled', async () => {
       jest
@@ -314,6 +356,10 @@ describe('ClaimsService', () => {
               decryptDeterministic: jest.fn((v: string) => v),
             },
           },
+          {
+            provide: WebhooksService,
+            useValue: mockWebhooksService,
+          },
         ],
       }).compile();
 
@@ -365,6 +411,38 @@ describe('ClaimsService', () => {
       );
     });
 
+    it('should enqueue claim.disbursed webhooks after a successful disbursement', async () => {
+      jest
+        .spyOn(prismaService.claim, 'findUnique')
+        .mockResolvedValue(mockClaim);
+      type TxClient = { claim: { update: jest.Mock } };
+      jest
+        .spyOn(prismaService, '$transaction')
+        .mockImplementation(
+          async (callback: (tx: TxClient) => Promise<unknown>) =>
+            callback({
+              claim: {
+                update: jest.fn().mockResolvedValue({
+                  ...mockClaim,
+                  status: ClaimStatus.disbursed,
+                }),
+              },
+            }),
+        );
+
+      await service.disburse('claim-123');
+
+      expect(mockWebhooksService.enqueueEvent).toHaveBeenCalledWith(
+        'claim.disbursed',
+        expect.objectContaining({
+          event: 'claim.disbursed',
+          claim: expect.objectContaining({
+            id: 'claim-123',
+          }),
+        }),
+      );
+    });
+
     it('should throw NotFoundException if claim does not exist', async () => {
       jest.spyOn(prismaService.claim, 'findUnique').mockResolvedValue(null);