Why Node.js Notification Backends Need Attempt-Level Delivery, Polling, and Audit Records

DonovanPierce4012 — Thu, 06 Aug 2026 01:37:52 +0000

Short answer: build the notification center around immutable delivery attempts, not mutable message rows; accept each event once, create channel-specific attempts, append every state change to an audit log, and expose a cursor-based polling API over that history.

That answer is less glamorous than picking an email or SMS provider. It is also the part that keeps an OTP retry from becoming two texts, a marketing opt-out from becoming an argument with compliance, and a dashboard from claiming “sent” when all the backend really did was enqueue work.

I treat the center as an accounting system for communication. The event says what the application wanted. An attempt says what one channel worker tried. History says what changed and when. Keep those three ideas separate and the Node.js implementation becomes ordinary queue, database, and HTTP work. Blur them together and every delivery gap turns into archaeology.

What should a Node.js notification center backend record for email, SMS, event delivery history, and polling?

Start with the constraint: delivery is asynchronous, while product code wants an immediate answer. The POST that accepts an event cannot truthfully promise that an email reached an inbox or an SMS reached a handset. It can promise a narrower result: the event was accepted under an idempotency key and has a stable identifier. That distinction belongs in the API contract.

I use four records. notification_event holds the business intent, recipient reference, template version, policy class, and idempotency key. delivery_attempt represents one dispatch through one channel, with its own state and provider-neutral external reference. delivery_transition is an append-only account of state changes. preference_snapshot records the consent and suppression decision used when the attempt was created. The current status on an attempt is a cache for fast reads; the transitions are the audit evidence.

The names matter less than the boundaries. Never overwrite the original recipient, template version, or policy decision to make a retry look tidy. A retry is a new attempt linked to the same event. Likewise, don't put email and SMS status columns on the event row. That model breaks as soon as one channel retries, another is suppressed, or an OTP expires before a delayed worker handles it.

For password recovery and OTP flows, I apply the OWASP guidance at the policy edge: return consistent responses, rate-limit requests, generate tokens with an appropriate random source, store them securely, make them single-use, and expire them. The audit record should describe the policy outcome without storing the secret itself. For commercial email, the FTC guidance makes sender identity and opt-out handling part of the design, not copywriting cleanup after launch.

One hard rule follows: “accepted” is not “delivered.” Make that visible in names, metrics, and API responses.

Separate intent, attempts, and transitions

The write path should be short. In one database transaction, deduplicate the incoming event, save its policy snapshot, create eligible channel attempts, and append their initial transitions. Commit before workers can claim anything. A queue message should carry an attempt ID, not the full email body or phone number; the worker reloads the authoritative record and checks that the attempt is still claimable.

Here is the core contract in Python-shaped pseudocode. My production service can still be Node.js; this example deliberately shows the data flow rather than tying the design to a web framework or queue client.

from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Protocol


@dataclass(frozen=True)
class EventRequest:
    idempotency_key: str
    recipient_ref: str
    template_version: str
    channels: tuple[str, ...]


class Store(Protocol):
    def transaction(self): ...
    def find_event(self, idempotency_key: str): ...
    def insert_event(self, request: EventRequest, accepted_at: datetime): ...
    def policy_snapshot(self, recipient_ref: str, channel: str): ...
    def insert_attempt(self, event_id: str, channel: str, policy: dict): ...
    def append_transition(self, attempt_id: str, state: str, at: datetime): ...
    def page_transitions(self, recipient_ref: str, after: str | None, limit: int): ...


def accept_event(store: Store, request: EventRequest) -> dict:
    now = datetime.now(timezone.utc)
    with store.transaction():
        existing = store.find_event(request.idempotency_key)
        if existing:
            return {"event_id": existing.id, "accepted": True, "duplicate": True}

        event = store.insert_event(request, accepted_at=now)
        for channel in request.channels:
            policy = store.policy_snapshot(request.recipient_ref, channel)
            if not policy["eligible"]:
                continue
            attempt = store.insert_attempt(event.id, channel, policy)
            store.append_transition(attempt.id, "queued", at=now)

    return {"event_id": event.id, "accepted": True, "duplicate": False}


def poll_history(
    store: Store,
    recipient_ref: str,
    after: str | None = None,
    limit: int = 50,
) -> dict:
    bounded_limit = min(max(limit, 1), 100)
    rows, next_cursor = store.page_transitions(
        recipient_ref=recipient_ref,
        after=after,
        limit=bounded_limit,
    )
    return {"items": rows, "next_cursor": next_cursor}

Race it deliberately.

The idempotency check needs a database uniqueness constraint as its final referee; an application-level lookup alone can race. Workers need a comparable claim operation so two consumers don't send the same attempt. In a test environment, pause two event handlers after their lookups, release them together, and verify that one insert wins while the other returns the existing event. Repeat the same exercise at worker claim time. Then kill a worker after it claims an attempt but before handoff, and again immediately after handoff, because those two crash points demand different recovery decisions. Keep provider payloads out of the public history response, store only the diagnostic fields your team has deliberately approved, redact addresses and phone numbers from logs, and set retention by policy class rather than keeping everything forever. This is fussy work — exactly the sort I want finished before an urgent OTP incident.

How should the polling API expose audit and delivery history?

A polling endpoint is a read model, not a dump of your operational tables. I return transitions ordered by a stable cursor composed from the transition timestamp and unique ID. A client supplies after, receives a bounded page, and persists next_cursor. Offset pagination is awkward here because new rows arrive while a client walks the list; a cursor gives the client a clear continuation point based on the ordering contract.

Each item should identify the event, attempt, channel, public state, transition time, and a safe reason category such as suppressed_by_policy or expired. It should not expose an OTP, raw provider response, provider credential, full message body, or an unrestricted recipient identifier. Authentication answers who may call the endpoint; authorization still has to scope which user's records that caller may see.

Keep the state vocabulary small and define it yourself. I usually need accepted intent, queued attempt, handed-off attempt, a terminal delivery outcome, suppression, and expiry. Provider-specific statuses map into that vocabulary behind the adapter. Preserve the raw external reference privately when operations needs reconciliation, but don't make the UI understand every downstream dialect.

Polling also needs an explicit freshness promise. Return the server time and document that the history is eventually updated; don't have the client infer delivery from a missing row. Use conditional requests or a backoff schedule if the UI may sit open for hours. Your mileage may vary on the exact interval — OTP screens and an admin archive have very different urgency — but adding random jitter prevents every browser tab from waking at the same instant. This is where edge cases earn their keep: a callback can arrive before the worker commits its handoff transition, two callbacks can report the same state, and an older status can arrive after a newer one. Append all accepted observations with their source time, then calculate the public state using a monotonic transition policy. Don't rewrite history to make arrival order look causal.

Which delivery strategy fits after the constraints are clear?

Once the records and invariants are clear, the transport choice gets easier. Polling is a reasonable default for a notification center UI because the reader controls authentication, pagination, and rendering. Push mechanisms reduce visible delay, but they add connection lifecycle and replay questions. Provider callbacks are useful on the ingest side, where they update attempts; they are not automatically the right interface for your product clients.

Strategy	Good fit	Main trade-off	Failure handling I expect
Cursor polling	History pages, admin tools, ordinary web clients	Repeated reads and bounded freshness	Resume from the last committed cursor
Server-sent events	A signed-in screen needing quicker updates	Long-lived connections and reconnect state	Reconnect with a last-event marker, then reconcile
WebSocket	Existing bidirectional real-time infrastructure	More session and authorization machinery	Reconnect, reauthorize, and refill gaps from history
Client webhook	Machine-to-machine consumers	Public endpoint security and retry ownership	Sign deliveries, retry safely, and expose replay controls

The catch is that polling is not suitable when a verified alert must appear within a very tight latency budget and stale reads are unacceptable. Use a push channel there, but retain the history endpoint for recovery. Stick with polling when the product can tolerate bounded delay and the operational value of a simple stateless read path is higher than live updates.

Cost belongs in this comparison, though I don't lead with it. I got burned by a $1,842 messaging bill after a retrying event consumer created fresh send jobs instead of reusing the idempotency key; the dashboard showed healthy throughput while customers received duplicates, and I had assumed its rising line meant the queue was merely catching up. I ended up tracing a single business event across the consumer, job table, and handoff records before the duplicate fan-out became obvious. The fix was architectural: uniqueness at event acceptance, attempt claims in the database, and separate counts for accepted events, created attempts, and billable handoffs. That incident is why I distrust a single “messages sent” chart.

It stung.

Watch queue age, attempts per event, suppression rate by policy class, time from acceptance to handoff, time from handoff to terminal observation, callback deduplication, and polling lag. I'm not sure why teams still start with vendor success rate; without your own denominators and state definitions, that percentage can't explain where the gap began.

How can I roll out this model without duplicate sends?

Migration should begin in shadow mode. Keep the current sender authoritative while writing new event, attempt, and transition records beside it. Reconcile counts by channel and policy class, inspect mismatches, and verify that the read model never exposes secrets or cross-tenant data. No new worker sends yet.

Next, choose one low-risk notification class and make the new acceptance path authoritative for it. Pin the idempotency key to a business action, not an HTTP request ID, because an application retry represents the same intent. Deploy consumers with claim-before-send behavior, then test process crashes immediately before and after the handoff. The system should either leave an attempt safely claimable or preserve evidence that prevents an automatic second handoff.

OTP deserves a separate rollout lane. Exercise repeated requests, expired tokens, used tokens, suppressed recipients, and responses for known versus unknown accounts. Keep the user-facing response consistent with the OWASP guidance while giving authorized operators enough categorized history to diagnose delivery gaps. For commercial email, test preference changes and suppression between event acceptance and worker claim; decide in writing whether the snapshot or latest policy wins for each message class.

Finally, move the UI to the cursor API and compare its results with the old screen before retiring old status fields. Make rollback disable new claims without deleting history. Short version: migrate the ledger first, the sender second, and the UI last. That order gives the team evidence before it takes on delivery risk.

References

OWASP, “Forgot Password Cheat Sheet”: https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html
Federal Trade Commission, “CAN-SPAM Act: A Compliance Guide for Business”: https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business