Next.js SaaS core with conditional billing-webhook and ingress controls

Architecture

Build the SaaS as a Next.js application using server-side routes/actions for authenticated product operations, billing initiation, validated billing-webhook receipt, and transactional-email requests. Store application-owned users, tenant memberships, roles, account status, Stripe customer/subscription references, entitlement state, billing commands, verified webhook inbox records, and transactional email outbox records in PostgreSQL. Use Prisma for schema migrations and application data access.

Use Clerk for authentication, but authorize every protected server entry point from PostgreSQL membership, role, and account-status records. A valid identity session alone does not confer tenant access. Local account disabling is enforced on the next application authorization check; Clerk session revocation and identity lifecycle changes may be delayed and must be reconciled before relying on them for access decisions.

Use an application-owned billing-command ledger. Persist an immutable command ID, tenant-scoped logical-operation key, intended change, and stable provider-compatible idempotency/correlation value before calling Stripe. On timeout, interrupted response, or crash uncertainty, mark the command ambiguous. Reissue only the identical logical operation with the original key within validated provider guarantees; otherwise reconcile through a validated, queryable correlation value tied to the command ID. If neither is available, prohibit automatic reissue and require controlled reconciliation.

Do not expose a billing webhook endpoint until current provider documentation and integration validation establish raw-request preservation, authenticity verification, unique event identifiers, and applicable reconciliation behavior. Verify authenticity over raw request bytes before trusting any payload field. For verified events, durably commit a unique inbox record before acknowledgement, then apply state through transactional, leased processing. Reject unverified events without persisting business instructions or changing application state.

Run a durable recovery executor as a production prerequisite for billing and email workflows. It may be a scheduled invocation within the application, but must scan due billing commands, webhook inbox records, and email outbox records; use leases and bounded retries; reconcile ambiguous work; surface terminal exceptions for controlled handling; and be monitored.

Use Resend for transactional email. Create email outbox records transactionally with the related application action and process them through pending, sending, sent, unknown, and error states. Do not treat provider acceptance or delivery as proof of receipt or action.

Public deployment, TLS termination, reverse proxying, rate limiting, bot protection, backup storage, scheduling/executor operation, alerting, and monitoring require a separately validated deployment design before production use.

Implementation sequence

• Create Next.js server-side boundaries for protected product actions, billing commands, validated webhook receipt, email outbox creation, and the recovery executor; never expose provider secrets to browser code.
• Model PostgreSQL tables for identity mappings, tenants, memberships, roles, account status, billing references, entitlement state, billing commands, verified webhook inbox records, and email outbox records. Add immutable command IDs, unique logical-operation keys, leases, attempts, timestamps, state, and audit data needed for recovery.
• Use Prisma migrations with separate runtime and migration credentials. Keep schema-changing privileges out of routine application execution.
• For every protected action, validate the Clerk session and load current PostgreSQL membership, role, and account status before authorization. Deny disabled accounts from local application actions immediately on the next check; define reconciliation for delayed identity lifecycle or revocation changes.
• Derive tenant scope from verified server-side context and enforce it in every query and mutation. Do not accept browser-supplied tenant, role, billing, or entitlement claims as authority.
• Before each charge-affecting or billing-changing call, transactionally persist the billing command, immutable command ID, intended operation, and stable provider-compatible idempotency/correlation value. Serialize commands for the same customer or subscription.
• On timeout, unknown response, or interrupted billing execution, set the command to ambiguous. Before any reissue, reconcile by a validated provider lookup keyed to the immutable command ID or reuse the original idempotency key only within validated scope and retention guarantees. Otherwise hold the command for controlled reconciliation; never generate a new key to resolve ambiguity.
• Before enabling webhooks, validate the chosen provider procedure for raw-byte handling, signature/authenticity verification, event IDs, duplicate delivery, ordering, and authoritative-state retrieval. If verification is unavailable, reject the request without retaining payload instructions or mutating state.
• After successful raw-request verification, insert the webhook inbox record under a unique provider event ID and commit it before acknowledging delivery. On duplicate insert, acknowledge only the existing verified event without repeating effects.
• Process verified inbox events with retryable leased claims. In one transaction, lock or serialize the affected billing reference, compare against authoritative or reconciled state without overwriting a newer local transition, apply entitlement changes, write audit data, and mark the inbox event processed. Expired claims return to recoverable work; completion never precedes the committed transition.
• Implement the recovery executor before enabling billing workflows. It must periodically claim due inbox, billing-command, and email-outbox work; use bounded retries and leases; reconcile ambiguous billing and email outcomes; prevent concurrent workers from duplicating effects; and route exhausted or irreconcilable work to controlled operator handling.
• Create transactional email outbox records with pending, sending, sent, unknown, and error states. Lease a record before dispatch; mark timeout or post-dispatch crash uncertainty as unknown. Reconcile with validated provider message IDs, idempotency, or delivery events where available; otherwise apply message-specific duplicate-tolerance rules and controlled operator resolution rather than blind retries.
• Keep invitation and recovery links expiring and single-use at the application layer. Treat email as at-least-once where provider deduplication or lookup is unavailable, with possible duplicates and no guarantee of delivery.
• Select and validate deployment, TLS, backups, executor scheduling, monitoring, and alerting before production use. If Nginx is adopted, validate the exact edition/version, directives, trusted-proxy handling, and client-IP controls before relying on them.
• Validate authorization, tenant isolation, session-disable behavior, billing ambiguity, duplicate and interrupted webhook processing, out-of-order reconciliation, email unknown-outcome recovery, restore, and incident procedures before release; record unresolved provider assumptions.

Security and operations

• Keep Clerk, Stripe, Resend, database, and application secrets in a deployment-selected managed secret mechanism; restrict access, rotate credentials, and never commit secrets.
• Outbound billing request idempotency is distinct from inbound webhook deduplication. Persist the same logical command and stable key before dispatch; a new key must never be used to resolve an unknown charge-affecting outcome.
• Do not trust webhook payload fields until authenticity is verified against raw request bytes. Reject unverifiable events without retaining untrusted business instructions or allowing state changes.
• A verified webhook inbox record must be committed before acknowledgement. Atomically commit each entitlement transition with terminal inbox state, and use leased claims plus serialization so duplicate delivery, worker crashes, reconciliation, and concurrent processing cannot repeat effects or revert newer state.
• Treat all email provider timeouts and post-dispatch crashes as unknown outcomes, not failures. Reconcile when validated provider correlation exists; otherwise document possible duplicate delivery and use message-specific controlled resolution.
• Server-side authorization uses current application membership and account status on each state-changing entry point. Identity-provider session revocation or lifecycle synchronization can lag; do not promise instantaneous identity-wide disablement beyond the local authorization check.
• Encrypt backups, separate backup access from routine application access, and define restoration, retention, deletion, and key-recovery procedures. The stack does not establish a complete backup implementation.
• The recovery executor, its schedule, lease recovery, bounded retry policy, monitoring, and operator escalation are deployment prerequisites, not implicit effects of HTTP delivery.
• Minimize personal and billing-related data, restrict administrative access, log privileged changes, and define retention and deletion procedures consistent with applicable obligations.

Limitations

• The catalogue does not substantiate Stripe webhook signing, raw-payload requirements, event-ID behavior, ordering, state retrieval, or reconciliation capabilities for the selected integration. These must be validated before enabling billing webhooks.
• The catalogue does not substantiate Stripe idempotency scope, retention, lookup, or correlation semantics for the intended billing operations. Until validated, ambiguous commands cannot be automatically reissued unless a validated provider correlation lookup establishes the outcome.
• The catalogue does not substantiate Resend idempotency, message lookup, delivery events, or reconciliation behavior. Where unavailable, transactional email is at-least-once, may duplicate, and requires message-specific operator handling for unknown outcomes.
• No scheduler, worker platform, queue, monitoring system, alert-delivery service, hosting, TLS, proxy, WAF, or backup product is established by this stack. A durable scheduled recovery executor and its supervision remain future deployment implementation work before billing workflows are enabled.
• The catalogue does not verify Clerk session lifecycle, revocation timing, account recovery, lifecycle synchronization, selected identity methods, or data handling. Local authorization checks mitigate access within the application but do not establish instantaneous provider-wide revocation.
• The catalogue does not substantiate any selected Nginx edition/version or support for intended body limits, route-specific rate limits, or timeouts.
• The catalogue does not verify Stripe business eligibility, regional availability, payment methods, tax responsibilities, subscription semantics, customer portal behavior, or applicable reconciliation capabilities.
• No pricing, capacity, recovery objective, uptime, live-test result, or production-deployment claim is made from the supplied catalogue.

Alternatives to consider

• Use product 42 (Auth0) instead of product 43 (Clerk) after validating the required login methods, session controls, recovery workflow, lifecycle synchronization, administrative controls, and data handling.
• Use product 8 (Paddle) instead of product 7 (Stripe API) if a merchant-of-record approach fits the business, after validating eligibility, tax responsibilities, subscription workflows, event behavior, and reconciliation needs.
• Use product 12 (Postmark) or product 13 (SendGrid) instead of product 11 (Resend) after independently evaluating domain setup, deliverability operations, suppression handling, event behavior, and data-location requirements.
• Use product 88 (Drizzle ORM) instead of product 87 (Prisma ORM) if its migration and access model better fits the application, after validating PostgreSQL support and team operating practices.
• Consider product 70 (Nginx) for ingress only after documenting the selected edition/version, applicable directives, trusted-proxy model, and load/rejection test results.
• Consider product 91 (RabbitMQ) or product 92 (Temporal) if validated workload requirements exceed a database-record-based processing design.