Add dead-letter alarm and route for inspecting failed webhook deliveries

[thlpkee20-wq]

Summary

Add dead-letter alarm and route for inspecting failed webhook deliveries

Why this matters

WebhookQueue in src/index.ts marks exhausted deliveries as dead_letter in webhook_deliveries, but there is no metric, alarm, or operator-facing route to surface them, so failed customer integrations go unnoticed. Expose a dead_letter count gauge per endpoint and an admin route returning the most recent dead-lettered deliveries for inspection and replay.

Scope

Implement the requested behavior across src/index.ts, src/db/repositories/webhookEndpointRepository.ts, src/routes/webhooks.ts, GET /admin/webhooks/:endpointId/dead-letters, POST /admin/webhooks/dead-letters/:id/replay. The solution must preserve existing compatibility, authorization, and production safeguards.

Priority

High

Acceptance criteria

• The requested behavior is implemented across src/index.ts, src/db/repositories/webhookEndpointRepository.ts, src/routes/webhooks.ts, GET /admin/webhooks/:endpointId/dead-letters, POST /admin/webhooks/dead-letters/:id/replay with a clear, reviewable contract.
• Security, authorization, validation, and data-integrity requirements in the repository context are enforced and covered by tests.
• Failure, retry, timeout, concurrency, and boundary behavior is explicit and produces safe, diagnosable outcomes where applicable.
• Regression coverage includes empty, invalid, duplicate, and boundary inputs relevant to this flow.
• Existing API, storage, and deployment compatibility is preserved unless a migration is explicitly documented.

Validation

Include focused tests for:

• happy paths;
• invalid input and authorization boundaries;
• concurrency, retries, or failure recovery;
• backward compatibility;
• relevant integration or contract behavior.

The implementation must pass the repository’s existing build, lint, test, and formatting checks (use npm test where applicable).

Non-goals

• Typo-only, formatting-only, or documentation-only changes.
• Unrelated refactors or dependency upgrades.
• Weakening security, authorization, CI, or production safeguards.
• Changing public behavior outside this issue’s scope.

Contributor application

Before implementation, comment with:

1. relevant experience;
2. a concise implementation approach;
3. expected files or modules affected;
4. an estimate for opening the first PR.

Wait for maintainer assignment before coding.

PR requirements

Use a feature branch and include Closes #.

The PR must:

• address every acceptance criterion;
• link each criterion to code and tests;
• explain security and failure-mode handling;
• include meaningful regression coverage;
• document compatibility or migration considerations;
• pass the repository checks.

Reward-readiness

This is a substantive quality issue. Merge status does not guarantee reward eligibility; final evaluation is determined separately.

Implementation context

Description

WebhookQueue in src/index.ts marks exhausted deliveries as dead_letter in webhook_deliveries, but there is no metric, alarm, or operator-facing route to surface them, so failed customer integrations go unnoticed. Expose a dead_letter count gauge per endpoint and an admin route returning the most recent dead-lettered deliveries for inspection and replay.

Requirements and context

• Must be secure, tested, and documented
• Should be efficient and easy to review
• Relevant code: src/index.ts (WebhookQueue), src/db/repositories/webhookEndpointRepository.ts, src/routes/webhooks.ts
• The replay endpoint must require admin auth and must idempotently re-enqueue the original event_id

Suggested execution

• Fork the repo and create a branch
• git checkout -b feat/webhook-dead-letter-route
• Implement changes
  • Add webhook_dead_letter_total{endpoint} to the metrics collector
  • Add GET /admin/webhooks/:endpointId/dead-letters listing recent failures
  • Add POST /admin/webhooks/dead-letters/:id/replay that re-enqueues idempotently
• Validate security and correctness assumptions

Test and commit

• Run tests
  • npm test
• Cover edge cases
  • Replay does not produce duplicate event_id, non-admin returns 403, pagination guard, cardinality cap on endpoint label
• Include test output and notes

Example commit message

feat: expose webhook dead-letter inspection and replay

Guidelines

• Minimum 95 percent test coverage
• Clear documentation
• Timeframe: 96 hours

[keljoshX]

@keljoshX has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainer, i can efficiently implement this. kindly assign me, thanks you

ℹ️ Repo Maintainers: To accept this application, review their application or assign @keljoshX to this issue.

[Windowlight]

@Windowlight has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I’m interested in contributing to this issue. I’ll begin by reviewing the existing architecture and related code, then implement the requested changes while following the project’s existing conventions. I’ll include appropriate tests and keep the PR focused, documented, and easy to review.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Windowlight to this issue.

[drips-wave]

Congratulations, @Windowlight! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Windowlight: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Windowlight's PR #896 was approved and merged by @thlpkee20-wq.

🏆 @Windowlight: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,462 total points). Track your full progress on GrantFox.

👏 Great work, @Windowlight! Keep contributing to RevoraOrg.