feat(api): implement webhook event dispatch system

[David-patrick-chuks]

Overview

This PR adds a webhook event dispatch system to apps/api so merchant systems can be notified when payment lifecycle events occur. It introduces support for payment.created, payment.detected, payment.confirmed, and payment.failed, and sends a standardized JSON payload containing the event type, data object, and timestamp.

Related Issue

Closes #15

Changes

⚙️ Webhook Dispatch System

• [ADD] apps/api/src/webhooks/webhooks.service.ts

  • Added the core webhook dispatch service for payment lifecycle events.
  • Implemented support for payment.created, payment.detected, payment.confirmed, and payment.failed.
  • Standardized the payload format to include event, data, and timestamp.
  • Added JSON POST delivery with a configurable timeout.
  • Added optional HMAC SHA-256 signing for webhook endpoints with a shared secret.

• [ADD] apps/api/src/webhooks/interfaces/webhook-event.interface.ts

  • Defined the supported webhook event types.
  • Added shared interfaces for webhook payloads, endpoints, and delivery results.

• [ADD] apps/api/src/webhooks/interfaces/dispatch-webhook.interface.ts

  • Added request and response interfaces for webhook dispatch operations.

🌐 Webhook API Surface

• [ADD] apps/api/src/webhooks/webhooks.controller.ts

  • Added a public POST /webhooks/dispatch endpoint to trigger webhook dispatch.
  • Accepts a standardized event, payload data, and one or more target endpoints.

• [ADD] apps/api/src/webhooks/webhooks.module.ts

  • Added a dedicated NestJS module for webhook dispatch.
  • Exported the webhook service for reuse by future payment lifecycle code.

• [MODIFY] apps/api/src/app.module.ts

  • Registered the new WebhooksModule in the API app.

🧪 Tests

• [ADD] apps/api/src/webhooks/webhooks.service.spec.ts
  • Added tests for standardized payload creation.
  • Added tests for signature generation.
  • Added tests for webhook delivery behavior.
  • Added validation coverage for empty endpoint lists.

🔧 Configuration

• [MODIFY] apps/api/.env.example
  • Added WEBHOOK_TIMEOUT_MS to configure webhook request timeouts.

Verification Results

Acceptance Criteria	Status
Supports payment.created event	✅
Supports payment.detected event	✅
Supports payment.confirmed event	✅
Supports payment.failed event	✅
Payload includes event, data, and timestamp	✅
Webhook dispatch logic is implemented in the API	✅
API build passes successfully	✅
Webhook service tests pass successfully	✅

How to Test

# 1. Confirm you're on the branch
git branch --show-current

# 2. Run the webhook unit tests
pnpm --filter api test -- --runInBand webhooks.service.spec.ts

# 3. Verify the API builds successfully
pnpm --filter api build

# 4. Optional: run the API locally
pnpm --filter api start:dev

# 5. Optional: test the webhook dispatch endpoint
curl -X POST http://localhost:3000/webhooks/dispatch \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment.confirmed",
    "data": {
      "paymentId": "pay_123",
      "merchantId": "merchant_456",
      "amount": "100.00",
      "currency": "USD"
    },
    "endpoints": [
      {
        "url": "https://example.com/webhooks",
        "secret": "shared-secret"
      }
    ]
  }'

# 6. Optional: inspect the changed files
git diff -- apps/api/src/app.module.ts apps/api/src/webhooks apps/api/.env.example

Screenshots

✅ Webhook service tests pass

A screenshot of:

pnpm --filter api test -- --runInBand webhooks.service.spec.ts

✅ API build passes

A screenshot of:

pnpm --filter api build

✅ Webhook dispatch endpoint works

A screenshot of:

curl -X POST http://localhost:3000/webhooks/dispatch \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment.confirmed",
    "data": {
      "paymentId": "pay_123",
      "merchantId": "merchant_456",
      "amount": "100.00",
      "currency": "USD"
    },
    "endpoints": [
      {
        "url": "https://example.com/webhooks",
        "secret": "shared-secret"
      }
    ]
  }'

[vercel]

@David-patrick-chuks is attempting to deploy a commit to the missblue00's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@David-patrick-chuks Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[MissBlue00]

@David-patrick-chuks the ci/cd check failed, please resolve