Node.js SaaS Error Alerting API: Reconstructing Checkout Attempts from Events

TL;DR: For a Node.js SaaS error alerting API, preserve queryable checkout events, then let a cron worker poll them with a durable cursor and notify your support channel. The deciding constraint is incident reconstruction: an alert that says "checkout failed" is cheap to send and expensive to investigate. A useful record connects the customer report, workflow step, deployment, and notification without storing payment details. For a small Node.js SaaS, I would start with polling rather than make alert delivery depend on the request that just failed. The request path records the event; a separate worker reads it. That split adds one cursor and one scheduled job, but it gives support a stable artifact after the original process or chat integration is gone. What should a Node.js SaaS error alerting API let you poll? The first design is tempting: catch an exception and post its message to a chat webhook. It feels finished because the message arrives quickly. It is not enough for customer support. A customer may report the problem hours later with an order reference, while the alert contains only a stack trace and a timestamp from a different clock. That's the trap. Keep the failure envelope narrow. A practical record needs an event ID, occurrence time, checkout attempt ID, workflow step, normalized error class, deployment identifier, and trace ID when one exists. Include a retry count and final outcome so a transient failure does not look identical to an abandoned purchase. Do not put card data, session secrets, raw request bodies, or unrestricted model prompts in this record. OpenTelemetry treats logs as timestamped records and describes correlation through trace and span identifiers. That makes the failure record useful even when application logs, traces, and support data live in separate stores. The standard supplies correlation vocabulary; it does not choose your retention period, redaction policy, or alert threshold. Those remain application decisions. One constraint matters more than field count: the checkout attempt ID must be searchable from the identifier support actually receives. Otherwise the telemetry is rich and operationally stranded. A focused event and polling boundary The write path should acknowledge only after the failure record is durably accepted by the application's event store. Notification is downstream work. This small TypeScript boundary lets storage and transport change without changing the event shape. type CheckoutFailure = { eventId: string; occurredAt: string; attemptId: string; step: "inventory" | "payment" | "confirmation"; errorClass: string; deploymentId: string; traceId?: string; retryCount: number; outcome: "retrying" | "failed" | "recovered"; }; type EventPage = { events: CheckoutFailure[]; nextCursor: string }; interface FailureStore { append(event: CheckoutFailure): Promise; readAfter(cursor: string, limit: number): Promise; } interface AlertSink { send(summary: string, dedupeKey: string): Promise; } Enter fullscreen mode Exit fullscreen mode The polling worker owns progress. It reads a bounded page, selects terminal failures, sends useful summaries, and commits the returned cursor only after successful delivery. Use the event ID as the notification deduplication key. If the process stops after send but before the cursor commit, the next run may repeat the send; the sink can suppress that duplicate. The trade-off is explicit: this design accepts possible duplicate delivery because silently skipping a checkout failure damages reconstruction more than a repeated internal alert. That choice also keeps a Slack webhook, email adapter, or another destination outside the evidence path; a destination outage delays notification but does not erase the event that a later poll must find. async function pollFailures( store: FailureStore, sink: AlertSink, cursor: string ): Promise { const page = await store.readAfter(cursor, 100); for (const event of page.events) { if (event.outcome !== "failed") continue; const trace = event.traceId ? ` trace=${event.traceId}` : ""; await sink.send( `Checkout ${event.attemptId} failed at ${event.step}; ` + `class=${event.errorClass} deploy=${event.deploymentId}${trace}`, event.eventId ); } return page.nextCursor; } Enter fullscreen mode Exit fullscreen mode A page size of 100 is an example control, not a universal tuning target. Pick a bound from payload size, worker deadline, and the burst you can replay without overwhelming the destination. Small pages reduce replay work; large pages reduce query overhead. Measure both. The gaps that produce misleading alerts Polling creates a new failure mode: silence can mean either "no checkout failures" or "the poller stopped." Record a heartbeat separately and alert on cursor age. The cursor should be monotonic under the store's ordering contract, and concurrent workers need a lease or compare-and-set update so an older cursor cannot overwrite a newer one. Classification is another trap. Grouping every exception message creates high-cardinality noise because messages often contain IDs or changing values. Normalize to a controlled error class, while keeping original diagnostic detail in access-controlled telemetry. Support needs the stable class; engineering may need the stack and correlated trace. Those are different views of the same incident. Retries complicate the story. A payment call that fails once and then succeeds should remain observable, but paging a person for it may be wrong. Alert from the terminal workflow outcome, and retain intermediate attempts for reconstruction. Conversely, a missing completion event may indicate a stalled workflow even though no exception was recorded. A scheduled query can identify attempts that entered a step but produced neither success nor terminal failure within the application's expected window. Test the ugly boundaries. Inject two identical pages, stop the worker between delivery and cursor commit, and delay events so occurrence order differs from ingestion order. Verify that redaction tests reject prohibited fields before deployment. These cases reveal more than a happy-path webhook test. Choosing the interface without choosing a vendor A suitable query API supports cursor pagination with deterministic ordering, filters on occurrence time and workflow fields, bounded responses, and a documented retention contract. It should expose enough information to detect ingestion delay. A webhook can complement that interface for low latency, but it should not be the only copy of the event. Email, Slack, or another chat destination is not the system of record. This polling design is an alternative to coupling evidence retention to notification delivery. Capability Why it matters Rejection signal Stable event identity Deduplicate replayed notifications Identity changes between queries Durable cursor Resume after worker restarts Late records can be skipped without a stated contract Attempt and trace correlation Move from a report to diagnostic context Only free-form messages are searchable Explicit retention Know how long reconstruction remains possible Retention is unknown or implicit Exportable records Preserve evidence across tooling changes Data can only be viewed in one UI Latency matters, but it is not the first filter here. A five-second notification with no attempt ID can waste more operator time than a one-minute poll that arrives with the exact failed step and deployment. Set the interval from the response objective for checkout support, then observe actual event-to-alert delay rather than assuming the scheduler runs on time. Measure this before copying the design Track event ingestion delay, cursor age, duplicate notification count, poll duration, page saturation, and the fraction of alerts that support can join to a checkout attempt. Track recovered retries separately from terminal failures. The useful question is not how many messages were sent. It is how often one alert supplied enough context to reconstruct the customer's path without searching raw production data. Start with one terminal failure class and one support destination. Run forced failures in a non-production checkout flow, restart the poller at each commit boundary, and confirm that every event is eventually visible with duplicates bounded by the deduplication policy. Expand coverage only after cursor, redaction, and correlation behavior is measurable. Simple wins. The smallest credible alerting system is a durable event, a resumable reader, and a notification carrying the identifiers needed for later investigation. References https://opentelemetry.io/docs/concepts/signals/logs/