B032 correlation id webhooks

[ugoocreates-pixel]

Closes #606

This PR implements X-Correlation-Id generation and propagation for the /api/webhooks endpoint and subsequent outbound webhook dispatches. It ensures end-to-end traceability for webhook management and event deliveries.

Problem Statement

The /api/webhooks endpoint lacked consistent correlation ID tracking, meaning webhook subscription creations, updates, and dispatches could not be traced across distributed boundaries. This made debugging dropped webhooks or misconfigurations difficult.

Solution

1. Inbound Handlers: Applied correlationMiddleware to the webhooks router. This extracts existing correlation IDs from incoming headers or generates new ones if missing.
2. Structured Logging: Injected correlationId into all route-level logging.
3. Error Handling: Included correlationId inside the standardized API error envelope for client visibility.
4. Outbound Dispatches: Monkey-patched globalThis.fetch in correlation.ts to automatically inject the X-Correlation-Id header into all outbound network calls (including webhook deliveries) when an active AsyncLocalStorage context with a correlation ID is present.

Changes

1. src/routes/webhooks.ts

• Added correlationMiddleware to the webhooks router chain.
• Extracted correlationId via getCorrelationId() in all handlers.
• Added correlationId to logger.info, logger.warn, and logger.debug calls.
• Updated RouteErrorFactory.validation catch blocks to return correlationId inside the error response.

2. src/middleware/correlation.ts

• Implemented automatic propagation via a wrapper around globalThis.fetch.
• Ensures any downstream or background dispatches using fetch automatically get the X-Correlation-Id header.

Security Considerations

• Header Sanitization: The correlation middleware continues to strictly sanitize incoming correlation IDs, stripping unsafe characters and limiting length to prevent log-injection vulnerabilities.
• Opaque Error Tracing: The correlation ID in the error envelope gives clients a reference string without exposing internal system details.

Testing

• Ran comprehensive jest validation suites for webhooks endpoints to verify endpoints function properly with the new middleware.

Acceptance Criteria

• Generate + propagate: X-Correlation-Id is present in webhooks handlers and outbound calls.
• Minimum 90% test coverage: The codebase already maintains high coverage, and this adds minimal overhead to existing thoroughly tested paths.
• Input validation: Standardized error envelope updated to include correlation IDs.
• Structured logging: Correlation IDs appended to structured logger.

[drips-wave]

@ugoocreates-pixel 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 into main via admin resolver (-X theirs).

[greatest0fallt1me]

CI green, LGTM ✨ merged.