feat: metrics on /api/webhooks

[Paranoa-dev]

feat: metrics on /api/webhooks

Summary

Adds Prometheus histogram and counter metrics for all /api/webhooks endpoints, following the established usersMetrics.ts pattern from /api/users.

Changes

New file: src/metrics/webhooksMetrics.ts

Express middleware that tracks per-request metrics using process.hrtime.bigint() and res.on("finish", ...):

• webhooksEndpointRequestsTotal (Counter) — incremented on every response finish with labels {method, route, status}
• webhooksEndpointDuration (Histogram) — observed on every response finish with the same labels

Route sanitization collapses UUIDs and numeric IDs to /:id for label cardinality control.

Modified: src/metrics/registry.ts

Added two new metrics:

webhooks_endpoint_requests_total{method, route, status}  // Counter
webhooks_endpoint_duration_seconds{method, route, status} // Histogram

Buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5, 10] (same as all existing histograms).

Modified: src/routes/webhooks.ts and src/routes/adminWebhooks.ts

Wired webhooksMetricsMiddleware before requireAdmin so it captures all responses including auth failures (403), validation errors (400), and successful responses (200).

Endpoints Covered

Method	Route	Status Codes Tracked
GET	/api/webhooks	200, 400, 403
GET	/api/admin/webhooks/dlq	200, 403
POST	/api/admin/webhooks/dlq/:id/replay	202, 400, 403, 404, 409

Tests

New file: tests/webhooksMetrics.test.ts

13 tests, all passing:

GET /api/webhooks (5 tests):

• Counter increments with method/route/status labels on 200
• Histogram observes duration on 200
• Records status=403 for unauthenticated requests
• Records status=403 for non-admin token
• Records status=400 for invalid query params

GET /api/admin/webhooks/dlq (3 tests):

• Counter increments on 200
• Histogram observes duration
• Records status=403 for unauthenticated

POST /api/admin/webhooks/dlq/:id/replay (3 tests):

• Counter increments on 404 (not found)
• Records status=403 for unauthenticated
• Histogram observes duration

Label structure (2 tests):

• Histogram includes method, route, and status labels
• Counter includes method, route, and status labels

Design Decisions

• Middleware placement: webhooksMetricsMiddleware is placed before requireAdmin so it captures all responses including auth failures — matching the usersMetricsMiddleware pattern in users.ts
• Labels: method, route, status — identical to the /api/users metrics for consistency
• Route sanitization: UUIDs and numeric IDs collapsed to /:id to prevent label cardinality explosion
• Measurement: process.hrtime.bigint() for nanosecond precision, same as existing metrics

Files Changed

File	Action	Lines changed
src/metrics/registry.ts	Modified	+15
src/metrics/webhooksMetrics.ts	Added	+28
src/routes/webhooks.ts	Modified	+2
src/routes/adminWebhooks.ts	Modified	+2
tests/webhooksMetrics.test.ts	Added	+357

Checklist

• Implementation matches the description
• Tests added and passing (13/13)
• ESLint clean
• Follows repo conventions (same pattern as usersMetrics)
• Labels: method, route, status
• Histogram buckets match existing histograms

Closes #434

[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