Signed, idempotent webhook delivery for subscriber integrations

[christabel888]

Overview

Build backend/webhooks/ to send outbound event notifications (corridor alerts, anomaly detections, snapshot completions) to subscriber-configured URLs. Design authenticity and deduplication in from the start, following the Stripe/GitHub webhook convention subscribers will already be familiar with.

Why this is hard

At-least-once delivery inherently means subscribers can receive the same event twice, so the system has to give a stable idempotency key per logical event, not just per delivery attempt, or every integration built on top independently reinvents deduplication. Signature verification is the only thing standing between a legitimate alert and anyone who finds a subscriber's webhook URL injecting fake payloads — a real risk for a financial-analytics product, since a forged "corridor reliability has collapsed" webhook could trigger real downstream decisions.

What to build

Suggested layout:

backend/webhooks/
  mod.rs
  event.rs        # stable UUID per logical event, unchanged across retries
  sign.rs          # HMAC over payload with per-subscriber secret
  deliver.rs       # bounded retry-with-backoff on non-2xx
  status.rs        # queryable delivery history by event ID
backend/tests/
  idempotency_key_test.rs
  tampered_payload_test.rs

Implementation steps:

1. Build event.rs to assign a stable idempotency key per logical event, unchanged across retries.
2. Build sign.rs: HMAC-sign the outbound payload with a per-subscriber secret established at subscription time, delivered in a header.
3. Build a documented, bounded retry-with-backoff policy in deliver.rs, and status.rs for subscribers to query delivery status by event ID.
4. Write idempotency_key_test.rs and tampered_payload_test.rs.

Acceptance criteria

• Every delivery includes a stable per-event idempotency key across retries.
• Outbound payloads are HMAC-signed and documented for consumers.
• Retry policy is bounded and delivery status is queryable.
• Both tests above pass.