feat: /api/webhooks/health endpoint (v7)

[Paranoa-dev]

Closes #435

---

feat: /api/webhooks/health endpoint (v7)

Summary

Add a focused health probe endpoint for the webhook delivery subsystem at GET /api/webhooks/health.

Motivation

The webhook delivery pipeline depends on two critical runtime dependencies: Postgres (where deliveries and subscriptions are stored) and Redis/BullMQ (the queue used by the webhook worker). While the existing /api/health/dependencies probe covers all four system-wide dependencies, operators need a narrow, webhook-specific health check that isolates just the webhook subsystem's dependencies for targeted alerting and load-balancer routing.

Implementation

New file: src/routes/webhooks/health.ts

• Route: GET /api/webhooks/health
• Pattern: Factory function createWebhooksHealthRouter(deps) with injectable probe functions for full testability
• Dependencies probed:
  1. database — Postgres via pool.query("SELECT 1")
  2. queue — Redis via redisConnection.ping()
• Composite status: "ok" when both pass, "down" when either fails
• HTTP status: 200 when ok, 503 when down
• Correlation ID: Accepts x-correlation-id header; generates UUID v4 if absent/empty
• Logging: Structured pino logs with correlation ID, status, per-dependency status, and elapsed time
• Error handling: Unexpected errors propagate to the global errorHandler middleware (returns 500)
• No caching: Fresh probe on every call (unlike /healthz/dependencies which caches for 5s)
• No auth: Returns no sensitive data; restrict at infrastructure level in production

Modified file: src/index.ts

• Import webhooksHealthRouter from ./routes/webhooks/health
• Mount at app.use("/api/webhooks/health", webhooksHealthRouter) (after /api/webhooks, before /api/users/health)

Response shape

{
  "status": "ok",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "checkedAt": "2026-07-26T12:00:00.000Z",
  "dependencies": {
    "database": {
      "status": "ok",
      "latencyMs": 2
    },
    "queue": {
      "status": "ok",
      "latencyMs": 1
    }
  }
}

When a dependency is down:

{
  "status": "down",
  "correlationId": "...",
  "checkedAt": "...",
  "dependencies": {
    "database": {
      "status": "down",
      "latencyMs": 100,
      "error": "Database unavailable"
    },
    "queue": {
      "status": "ok",
      "latencyMs": 1
    }
  }
}

Tests

New file: tests/webhooksHealth.test.ts — 28 tests, all passing

Category	Tests	Coverage
HTTP status codes	4	200 all-ok, 503 db-down, 503 queue-down, 503 both-down
Response body — status field	3	Composite status mapping verification
Response shape	7	Top-level fields, dependency entries, latencies, error fields
Correlation ID	4	Header echo, UUID fallback, empty string, uniqueness
Authentication	2	No auth required, ignores Authorization header
Error handling	4	Probe throws → 500, call count verification, parallel execution
Default router	1	Export validation
Edge cases	3	Error messages, zero latency

Test strategy: Injectable probe functions replace all external I/O. No real Postgres or Redis connections. Router mounted on minimal Express app with errorHandler.

Existing test regression check

Ran healthDependencies.test.ts and health.test.ts — both pass with no changes. The healthReady.test.ts failure (Redis connection refused) is pre-existing and unrelated.

Checklist

• Implementation matches the description
• Tests added and passing (28/28)
• Lint passing (eslint, no errors)
• Input validation at boundary (correlation ID handling)
• Structured logging with correlation IDs
• No sensitive data exposed
• Injectable dependencies for testability
• Documentation and inline comments
• No breaking changes to existing routes

[drips-wave]

@Paranoa-dev 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

[greatest0fallt1me]

Merged via direct push to main (admin)