signed webhook delivery with retries and a dead-letter queue

[mikewheeleer]

Summary

milestone release events are delivered to subscribers with no signature, no retry, and no visibility when delivery fails. Build a delivery pipeline with HMAC signing, bounded retries with backoff, and a dead-letter queue for exhausted deliveries.

Why this matters

Unsigned, best-effort webhooks are insecure and lossy. Signing lets subscribers verify authenticity; retries + DLQ make delivery reliable and observable.

Requirements

• Sign each payload with an HMAC (X-Signature + timestamp) subscribers can verify.
• Deliver with bounded retries and exponential backoff on 5xx/timeout.
• After exhausting retries, move the event to a dead-letter queue with the failure reason.
• Expose a way to list and replay dead-lettered events.

Technical guidance

• Include a timestamp in the signed payload to prevent replay.
• Bound payload size and make attempts/backoff configurable.

Edge cases — each must have a test

• successful delivery -> signature verifies
• 5xx then success -> retried and delivered
• retries exhausted -> lands in DLQ with reason
• replay from DLQ -> re-attempts delivery
• tampered payload -> signature check fails

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• npm run lint, npm test, and npm run build all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• A durable external queue (in-process DLQ is fine)
• Subscriber management UI

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[Chidi-Dev1]

Hi Maintainer,

I'm interested in working on this issue. I've understood the requirements and am ready to start immediately.

Please assign it to me. Thanks!