Web hook event

[KAMALDEEN333]

Webhooks & Reliable Event Delivery Module — Implementation Complete

Files Created (10 new)

Entities (src/infrastructure/webhooks/entities/)

• webhook-subscription.entity.ts — Per-subscriber config: URL, signing key (whsec_), events, retry/backoff params, rate limits, custom headers
• webhook-event.entity.ts — Event payload with type, aggregate ID, delivery/success/failure counters
• webhook-delivery.entity.ts — Individual delivery attempts: status tracking, request/response headers, retry scheduling
• webhook-dead-letter.entity.ts — Permanently failed deliveries with full attempt history for debugging

Services (src/infrastructure/webhooks/services/)

• webhook-hmac.service.ts — HMAC-SHA256 signing with timingSafeEqual verification
• webhook-subscription.service.ts — CRUD, signing key generation (whsec_<32-byte-hex>), key rotation, wildcard event matching
• webhook-delivery.service.ts — HTTP delivery with HMAC headers, exponential backoff + jitter (capped at 5 min), dead-lettering, DLQ retry, aggregated metrics
• webhook-event.service.ts — Event publishing, subscriber matching, Bull queue enqueue, event replay
• webhook-processor.service.ts — Bull @Processor("webhook-delivery") for async execution

Controller + Module

• webhook.controller.ts — Full REST API under /webhooks with Swagger decorators
• webhook.module.ts — Wires TypeORM entities, Bull queue, HttpModule

Files Modified (2)

• src/app.module.ts — Added WebhookModule import, 4 entity registrations
• src/config/env.validation.ts — Added WEBHOOK_* env vars + REDIS_HOST/REDIS_PORT/REDIS_PASSWORD

API Endpoints

Method | Path | Description -- | -- | -- POST | /webhooks/subscriptions | Create subscription (returns signing key once) GET | /webhooks/subscriptions | List subscriptions (keys stripped) GET | /webhooks/subscriptions/:id | Get subscription details PUT | /webhooks/subscriptions/:id | Update subscription DELETE | /webhooks/subscriptions/:id | Disable subscription POST | /webhooks/subscriptions/:id/rotate-key | Rotate HMAC signing key PUT | /webhooks/subscriptions/:id/status | Toggle active/paused/disabled POST | /webhooks/events | Publish event → auto-enqueue deliveries GET | /webhooks/events | List recent events (filterable by type) GET | /webhooks/events/:id | Event details + delivery records POST | /webhooks/events/:id/replay | Replay event to current subscribers GET | /webhooks/dead-letters | List DLQ entries POST | /webhooks/dead-letters/:id/retry | Retry a dead-lettered delivery GET | /webhooks/metrics | Delivery stats, success/fail rates, avg latency

Key Design Decisions

• HMAC-SHA256 per-subscriber signing with X-Webhook-Signature header (GitHub-style)
• Exponential backoff with 20% jitter, capped at 5 minutes
• Dead-letter queue after max retries, with manual retry capability
• Event replay for re-triggering historical events
• Bull queue (webhook-delivery) for async processing, consistent with existing email queue pattern
• Wildcard subscriptions via events: ["*"]

closes #128

[KAMALDEEN333]

@memplethee-lab pr sent please review