feat: webhook_dispatcher telemetry + email_sender_service signing/timeouts (#520–#523)

[success-OG]

Summary

Implements four self-contained issues for webhook dispatch telemetry/testing and email alert outbound hardening.

#520 — Add debug telemetry statements within webhook_dispatcher

• Added src/utils/webhook_dispatcher.ts as the webhook event notification service.
• Winston debug/info/error logs now trace the full pipeline with a shared traceId:
  • handler entered (route, body keys, contract id)
  • response sent (status, success)
  • delivery pipeline started / completed (ledger range, delivered/failed counts)
• src/routes/webhooks.ts now delegates subscribe/unsubscribe through the dispatcher and returns traceId in successful responses.
• Tests in __tests__/webhook_dispatcher.test.ts assert the required tracking indicators are present in logger metadata.

#521 — Add supertest verification validations for webhook_dispatcher

• Added __tests__/webhook_dispatcher_supertest.test.ts covering:
  • POST /api/webhooks/subscribe (200 success, missing fields, invalid event_types, * event types)
  • POST /api/webhooks/unsubscribe (200, 404, 400)
  • response traceId presence
  • back-to-back route exercise to confirm the suite completes without leaving dangling network sockets (DB handle closed in afterAll)

#522 — Implement signature checks within email_sender_service

• Added src/utils/email_sender_service.ts with:
  • signOutgoingWebhook() — HMAC-SHA256 over the canonical JSON body
  • verifyWebhookSignature() — timing-safe client-side verification of bare hex or sha256=<hex> headers
  • sendEmailAlert() — attaches X-Webhook-Signature on outbound alert webhooks
• Secret resolved from explicit arg or EMAIL_WEBHOOK_SECRET (documented in .env.example).
• Tests confirm signed payloads verify correctly and reject tampered bodies / wrong secrets.

#523 — Configure call timeout exceptions for email_sender_service

• Outbound calls use AbortController with a configurable timeout (EMAIL_SENDER_TIMEOUT_MS, default 5000ms).
• Stalled requests terminate, emit a Winston warn (call timeout threshold exceeded), and throw EmailSenderTimeoutError.
• Non-timeout failures still surface as errors without a timeout warning.
• Covered in __tests__/email_sender_service.test.ts.

Test plan

• npm test -- --testPathPatterns='webhook_dispatcher|email_sender_service|webhooks.test' --forceExit — 4 suites / 38 tests passed
• Confirm subscribe/unsubscribe still work against a local server
• Set EMAIL_WEBHOOK_SECRET and verify a receiver can validate X-Webhook-Signature
• Set a low EMAIL_SENDER_TIMEOUT_MS against a slow endpoint and confirm timeout warning + exception

Notes

• Existing /api/webhooks paths and response shapes are preserved; successful responses additionally include traceId.
• Issues are independent; shipped together on branch feat/520-523 for a single reviewable PR.

Closes #520
Closes #521
Closes #522
Closes #523

Made with Cursor

[drips-wave]

@success-OG 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