Reliable
Notification
Delivery
An observable, tenant-aware and at-least-once notification delivery platform.
Follow the event from intake to observable delivery.
The Challenge
Make notification delivery dependable for clients and explainable for operators.
Reliable Delivery
Confirm ownership, resolve the active subscription, send the HTTPS webhook and make every outcome durable.
Architecture at a Glance
Adapters change. Delivery rules remain.
The platform owns notification delivery and its operational history; the client owns the side effect after receiving the webhook.
A Notification Journey
One event, one durable history, explicit ownership at every step.
PostgreSQL claims prevent workers from processing the same due event.
Reliability Under Failure
Every outcome becomes an explicit state transition.
The client accepted the webhook and the final event state is durable.
- Result
- Success
- State
- COMPLETED
- Persisted evidence
- Attempt record with HTTP status and latency
- Next action
- No further delivery action
Self-Service and Tenant Isolation
The authenticated principal defines the tenant boundary.
Returns only the authenticated client's events with date, status and bounded pagination filters.
The event belongs to the authenticated client.
WHERE event_id = :notificationEventId
AND client_id = :clientIdFrom Complaint to Root Cause
“CLIENT002 is not receiving notifications.”
Prometheus evaluates a delivery deviation and Alertmanager exposes the active signal.
Payload and destination remain hidden.
Security Assessment
Prioritized risks, implemented controls and explicit residual exposure.
A client attempts to read or replay another client's notification.
Principal-derived client ownership and tenant predicates on every read and mutation.
WHERE event_id = :notificationEventId
AND client_id = :clientIdPublic API considerations
A07 and A02 require TLS at ingress, managed credential lifecycle, rate limits and private operational endpoints before public exposure.
Decisions and Engineering Confidence
Key decisions
- Rationale
- Durable state and coordinated claims without another runtime dependency.
- Trade-off
- Polling and claims consume database capacity.
Quality gate
Select a gate to see what confidence it adds.
Case Coverage
A focused V1 that makes delivery state, failure and ownership explicit.
API examples, lifecycle details, metrics and AI usage remain available as supporting material.