Stripe is clear about the rules: events are delivered at least once, may arrive out of order, and are retried with exponential backoff for up to three days if your endpoint doesn't return a 2xx. A handler has to be correct under all three. Here's a design for a Next.js App Router project that is.

The shape of it

Split the work in two:

1. The route handler verifies the signature, stores the event, and returns 200. It does nothing else.
2. A worker processes stored events, once each, and records that it did.

The handler stays fast, so Stripe doesn't time out and retry. Processing failures don't cost you the event, because it's already stored.

Store events with their Stripe ID as the key

create table stripe_events (
  id            text primary key,          -- evt_...
  type          text        not null,
  created_at    timestamptz not null,      -- from event.created
  payload       jsonb       not null,
  received_at   timestamptz not null default now(),
  processed_at  timestamptz,
  attempts      int         not null default 0,
  last_error    text
);

create index on stripe_events (received_at) where processed_at is null;

The primary key does the deduplication. A retried delivery hits the same id and is ignored.

The route handler

Signature verification needs the raw request body, exactly as Stripe sent it. In a route handler, read it with req.text() and don't parse it as JSON first:

// app/api/stripe/webhook/route.ts
import Stripe from 'stripe';
import { db } from '@/lib/db';
import { enqueue } from '@/lib/queue';

export const runtime = 'nodejs';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get('stripe-signature');
  if (!signature) return new Response('Missing signature', { status: 400 });

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  const inserted = await db.query(
    `insert into stripe_events (id, type, created_at, payload)
     values ($1, $2, to_timestamp($3), $4)
     on conflict (id) do nothing
     returning id`,
    [event.id, event.type, event.created, event],
  );

  if (inserted.rowCount === 1) {
    await enqueue('stripe-event', { id: event.id });
  }

  return new Response(null, { status: 200 });
}

Two details matter here. A duplicate delivery still gets a 200, because from Stripe's side it succeeded. And if enqueue fails after the insert, the event isn't lost: a sweeper job (below) picks up anything stored but not processed.

The worker: process once, under a lock

// lib/stripe/process-event.ts
export async function processStripeEvent(id: string) {
  await db.transaction(async (tx) => {
    const { rows } = await tx.query(
      `select payload from stripe_events
       where id = $1 and processed_at is null
       for update skip locked`,
      [id],
    );
    if (rows.length === 0) return; // already processed, or another worker has it

    const event = rows[0].payload as Stripe.Event;
    await handle(tx, event);
    await tx.query('update stripe_events set processed_at = now() where id = $1', [id]);
  }).catch(async (err) => {
    // the transaction rolled back, so record the failure outside it
    await db.query(
      'update stripe_events set attempts = attempts + 1, last_error = $2 where id = $1',
      [id, String(err)],
    );
    throw err;
  });
}

for update skip locked means two workers can't process the same event at the same time, and the business change and processed_at commit together. Either both happen or neither does.

If handle throws, the transaction rolls back and the event stays unprocessed for the sweeper to retry. The failure is recorded in a separate statement after the rollback, so the attempt count isn't lost with it.

Don't trust the order of events

For anything with a lifecycle, such as subscriptions, invoices or disputes, the payload in an old event may be stale by the time you process it. Use the event as a signal and read the current state from Stripe:

async function handle(tx: Tx, event: Stripe.Event) {
  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated':
    case 'customer.subscription.deleted': {
      const { id } = event.data.object as Stripe.Subscription;
      const sub = await stripe.subscriptions.retrieve(id);
      await tx.query(
        `update accounts
           set subscription_status = $1, price_id = $2
         where stripe_customer_id = $3`,
        [sub.status, sub.items.data[0]?.price.id ?? null, sub.customer],
      );
      return;
    }
    case 'checkout.session.completed': {
      // fulfil the order; the unique event id already guarantees this runs once
      return;
    }
    default:
      return; // stored for the record, nothing to do
  }
}

If a cancellation and a renewal arrive in the wrong order, both handlers read the same current subscription and write the same result. Order stops mattering.

Calling Stripe's API inside a database transaction holds row locks for the length of the request. That's fine at modest volume. If it isn't for you, fetch the object before opening the transaction and pass it in.

The sweeper

A scheduled job closes the gaps: events whose enqueue failed, and events whose processing failed and should be retried.

select id from stripe_events
where processed_at is null
  and received_at < now() - interval '5 minutes'
  and attempts < 10
order by received_at
limit 100;

Events that reach the attempt limit should alert someone rather than retry forever.

Test retries on purpose

The Stripe CLI forwards events to your local server and prints a signing secret for that session:

stripe listen --forward-to localhost:3000/api/stripe/webhook
stripe trigger checkout.session.completed

Then resend the same event with stripe events resend <event_id> and check that nothing happens twice. That one test catches most of the bugs this design exists to prevent.

Idempotency on the way in is the other half of the same problem; we covered client-side retries in idempotency keys for payment requests.

We build billing like this into the products we work on as part of our SaaS development and custom software projects.

How do you handle Stripe events today: inline in the handler, or stored and processed later?

The cause is almost never a bug in one system. It's a sync design where both Shopify and the ERP believe they own the stock number, and changes flow in both directions as adjustments. Each side applies the other's change on top of its own, and every order gets counted twice.

Here's how that happens, and a design that stops it.

How double counting happens

Take one unit sold online:

1. The order is placed. Shopify reduces its available quantity by 1.
2. The order is imported into the ERP as a sales order. The ERP allocates 1 unit, so its available quantity drops by 1.
3. The sync sees that Shopify's available quantity changed, and sends "-1" to the ERP as an adjustment.

The ERP has now deducted the same unit twice. Run the same pattern the other way, with ERP changes sent to Shopify as adjustments, and the store drifts too. The fix isn't a smarter adjustment. It's to stop sending adjustments.

Rule 1: one system owns the number

Pick one system of record for each stock figure. For most businesses with an ERP, that's the ERP: it sees purchase receipts, transfers, returns, B2B orders and other sales channels, and Shopify sees only its own orders.

Then the data flows in exactly two directions, and they carry different things:

• Orders flow from Shopify to the ERP. The ERP allocates stock against them like any other sales order.
• Available quantities flow from the ERP to Shopify. As absolute values, never as adjustments.

Nothing about stock levels flows from Shopify back to the ERP. Shopify's own decrement on checkout is a short-term reservation that the next sync replaces.

Rule 2: send "set to", never "change by"

An absolute value is idempotent. If the same update is sent twice, or arrives late, the result is still correct. An adjustment applied twice is a wrong number.

Shopify's GraphQL Admin API has a mutation for exactly this, inventorySetQuantities, which sets a named quantity at a location:

mutation SetAvailable($input: InventorySetQuantitiesInput!) {
  inventorySetQuantities(input: $input) {
    inventoryAdjustmentGroup { reason changes { name delta } }
    userErrors { field message code }
  }
}

{
  "input": {
    "name": "available",
    "reason": "correction",
    "referenceDocumentUri": "erp://inventory-sync/2026-11-02T10:15:00Z",
    "quantities": [
      {
        "inventoryItemId": "gid://shopify/InventoryItem/123",
        "locationId": "gid://shopify/Location/456",
        "quantity": 42,
        "compareQuantity": 40
      }
    ]
  }
}

compareQuantity makes the write conditional: Shopify rejects it if the current value isn't what you expected, so a sale that happened between your read and your write isn't silently overwritten. When that happens, re-read and recompute rather than retrying blindly. Field names around compare-and-set have changed between API versions, so check the reference for the version your app is pinned to. referenceDocumentUri ties each change to your sync run, which makes Shopify's inventory history readable later.

Rule 3: account for orders the ERP hasn't seen yet

This is the gap that causes overselling even with a clean one-way design. If the ERP computes availability at 10:15 and an online order placed at 10:14 hasn't been imported yet, the ERP still counts that unit as free. Push its number to Shopify and you've handed the sold unit back to the store.

The fix is to subtract orders that are in Shopify but not yet in the ERP before you push:

function availableToSell(sku: string, location: string): number {
  const erp = erpAvailable(sku, location);               // on hand minus ERP allocations
  const pending = ordersNotYetInErp(sku, location);       // placed in Shopify, not imported
  const buffer = safetyStock(sku, location);             // per-SKU cushion
  return Math.max(0, erp - pending - buffer);
}

Track "not yet imported" with an import watermark: the order sync records which Shopify orders it has written to the ERP, and anything newer is pending.

Map locations explicitly

Shopify holds inventory per location, and so does the ERP, but they rarely line up one to one. Keep an explicit mapping table, and decide what happens to warehouses that don't sell online: excluded, or pooled into one Shopify location. A product that exists in the ERP warehouse but has no mapped Shopify location is the most common reason a store shows zero for something that's on the shelf.

Handle webhooks as hints, not facts

Shopify webhooks such as orders/create and refunds/create are the fastest way to learn about changes, but they can arrive more than once and out of order. Treat them as a trigger to fetch current state, and deduplicate on the X-Shopify-Webhook-Id header before doing any work. Run a scheduled poll as well, so a missed webhook delays an update instead of losing it.

Reconcile every night

Even a good design drifts: manual edits in Shopify admin, a failed job, a location mapped wrong. A nightly job that compares the ERP's available-to-sell figure with Shopify's available quantity for every SKU and location, and reports the differences, turns silent drift into a short list someone can review each morning. Fix the cause of each difference rather than just overwriting it, or the same SKUs will appear again tomorrow.

The short version

• One owner per number, usually the ERP.
• Orders go to the ERP; absolute quantities come back.
• Subtract orders the ERP hasn't imported yet.
• Use compare-and-set, deduplicate webhooks, and reconcile nightly.

We build these integrations as part of our Shopify development and ERP development work, usually starting with the reconciliation report, because it shows where the numbers are drifting today.

Which system owns your stock number today, and does everyone on the team give the same answer?

Application logs and audit logs do different jobs. Application logs help your engineers debug. An audit log is a record your customer can rely on: who did what, to which thing, when, and from where. It has to be complete, hard to alter, kept for a known period, and visible to the customer's own admins.

Here's what buyers ask for, which events are worth recording, and a Postgres design that covers both.

What security reviews actually ask

The wording varies between questionnaires, but the questions cluster around six things:

1. Coverage. Are logins, permission changes, data exports and configuration changes recorded?
2. Attribution. Can you tell a human user from an API key, an automated job, or your own support staff?
3. Integrity. Can anyone, including your engineers, edit or delete entries?
4. Retention. How long are entries kept, and can that be extended by contract?
5. Access. Can the customer's admins search and export their own log without raising a ticket?
6. Export. Can it be streamed into their SIEM?

SOC 2 and ISO 27001 both expect logging and monitoring controls, so an auditor will ask the same things in a different form. Design for these six and you'll answer both.

Which events to record

Record actions that change access, configuration or data ownership. Don't record every page view; that's analytics, and it buries the events that matter.

• Authentication: sign-in, failed sign-in, sign-out, password reset, MFA enabled or removed, SSO settings changed.
• Access: user invited, removed, role changed, API key created or revoked.
• Data: export or bulk download, bulk delete, records shared outside the workspace.
• Configuration: billing, integrations, webhooks, retention and security settings.
• Support access: any time your own staff view or act inside a customer's workspace.

The last one is the event buyers ask about most, and the one teams most often forget to log.

The table

create table audit_events (
  id           bigint generated always as identity,
  tenant_id    uuid        not null,
  occurred_at  timestamptz not null default now(),
  actor_type   text        not null check (actor_type in ('user', 'api_key', 'system', 'support')),
  actor_id     text        not null,
  actor_label  text,                  -- email or key name at the time of the event
  action       text        not null,  -- e.g. 'member.role_changed'
  target_type  text,
  target_id    text,
  ip           inet,
  user_agent   text,
  request_id   text,
  changes      jsonb,                 -- {"role": ["member", "admin"]}
  metadata     jsonb       not null default '{}',
  primary key (tenant_id, occurred_at, id)
) partition by range (occurred_at);

create index on audit_events (tenant_id, action, occurred_at desc);

A few choices worth explaining:

• actor_label is copied in, not joined. If a user changes their email or is deleted, the log should still show who acted at the time.
• action uses a fixed vocabulary like member.role_changed rather than free text, so customers can filter on it and you can document it.
• changes stores before and after values for the fields that changed, not the whole record. For sensitive fields, store that the field changed and leave the value out.
• Partitioning by month makes retention cheap. On a partitioned table the primary key has to include the partition column, which is why occurred_at is in it.

Create a partition per month (pg_partman can do this for you), and retention becomes dropping a partition instead of a slow delete across millions of rows:

create table audit_events_2026_11 partition of audit_events
  for values from ('2026-11-01') to ('2026-12-01');

Make it append-only

The application should be able to add entries and read them, and nothing else:

revoke update, delete, truncate on audit_events from app_user;
grant insert, select on audit_events to app_user;

Run partition creation and retention from a separate role that the application never uses. That's the answer to "can your engineers edit the log?": not through the application, and the role that can drop old partitions is only used by a scheduled job.

Write the event in the same transaction

If the change commits and the audit insert fails, you have an action with no record. Write both in one transaction:

await db.transaction(async (tx) => {
  const before = await tx.query(
    'select role from memberships where id = $1 and tenant_id = $2 for update',
    [membershipId, tenantId],
  );
  await tx.query(
    'update memberships set role = $1 where id = $2 and tenant_id = $3',
    [newRole, membershipId, tenantId],
  );
  await tx.query(
    `insert into audit_events
       (tenant_id, actor_type, actor_id, actor_label, action, target_type, target_id, ip, request_id, changes)
     values ($1, 'user', $2, $3, 'member.role_changed', 'membership', $4, $5, $6, $7)`,
    [tenantId, user.id, user.email, membershipId, req.ip, req.id,
     { role: [before.rows[0].role, newRole] }],
  );
});

Put this behind a small audit() helper so every write path calls it the same way, and add a test per action that fails if the event isn't written.

Tamper evidence

Permissions stop the application from editing the log. They don't prove to an auditor that nobody with database access did. A simple way to make tampering detectable: once a day, a job computes a SHA-256 digest over each tenant's events for that day, in id order, and writes the digests to object storage with a retention lock (S3 Object Lock in compliance mode, for example). To verify a day later, recompute the digest and compare. If a row was changed or removed, the digests won't match.

This is cheaper and simpler than hash-chaining every row at write time, and it's enough to answer the integrity question honestly.

Give customers their own view

The feature that ends most audit-log questions on a sales call is a screen in the product: a filterable list for workspace admins, by user, action and date, with CSV export. For larger customers, add a stream to their SIEM, either as a webhook per event or as daily files dropped into a bucket they own.

Once that screen exists, the questionnaire answer changes from a paragraph of explanation to "yes, here's a screenshot".

We build this into multi-tenant products as part of our SaaS development work, usually before the first enterprise customer asks for it.

What's the audit-log question that slowed down a deal for you?

We had the same problem on our own site, so we stopped writing it by hand. Our llms.txt is generated from the same list of pages that builds sitemap.xml, so the two can't disagree. Here's the setup for a Next.js App Router site.

What llms.txt is, and what it isn't

llms.txt is a proposal, published by Jeremy Howard of Answer.AI in September 2024, for a Markdown file at the root of a site that gives language models a short, curated map of it. The format is simple:

• an H1 with the site or project name
• a blockquote with a one-paragraph summary
• optional plain paragraphs with extra context
• H2 sections, each a list of links in the form - [Title](url): note
• an optional section titled ## Optional for links a model can skip when its context is short

It isn't a standard, and none of the major AI search products has said it reads the file when ranking or citing pages. Treat it as cheap insurance: it takes an afternoon, it doesn't hurt, and if you log requests for it you'll see which crawlers actually fetch it. Don't treat it as a replacement for crawlable pages, a sitemap, or a robots.txt that lets AI crawlers in.

One page list, two outputs

The drift problem goes away when both files read from one source. Keep your public pages in a typed module:

// lib/site-pages.ts
export type SitePage = {
  path: string;
  title: string;
  summary: string;      // one line, written for a reader, not for keywords
  section: 'Services' | 'Case studies' | 'Insights' | 'Company';
  llms?: boolean;       // false = keep in sitemap, leave out of llms.txt
  optional?: boolean;   // true = list under "## Optional"
  lastModified?: string;
};

export const SITE_URL = 'https://example.com';

export const pages: SitePage[] = [
  { path: '/', title: 'Home', summary: 'Who we are and what we build.', section: 'Company' },
  { path: '/services/saas-development', title: 'SaaS development', summary: 'Multi-tenant SaaS products, from MVP to scale.', section: 'Services' },
  { path: '/privacy-policy', title: 'Privacy policy', summary: 'How we handle personal data.', section: 'Company', optional: true },
  // ...
];

If your pages come from a CMS or MDX files, build this array from that source instead. The point is that there's one array.

The sitemap reads it:

// app/sitemap.ts
import type { MetadataRoute } from 'next';
import { pages, SITE_URL } from '@/lib/site-pages';

export default function sitemap(): MetadataRoute.Sitemap {
  return pages.map((p) => ({
    url: `${SITE_URL}${p.path}`,
    lastModified: p.lastModified,
  }));
}

The llms.txt route

A route handler at app/llms.txt/route.ts serves /llms.txt. With dynamic = 'force-static' it's rendered once at build time, like the sitemap.

// app/llms.txt/route.ts
import { pages, SITE_URL, type SitePage } from '@/lib/site-pages';

export const dynamic = 'force-static';

const ORDER: SitePage['section'][] = ['Services', 'Case studies', 'Insights', 'Company'];

const line = (p: SitePage) => `- [${p.title}](${SITE_URL}${p.path}): ${p.summary}`;

export function GET() {
  const listed = pages.filter((p) => p.llms !== false);
  const core = listed.filter((p) => !p.optional);
  const optional = listed.filter((p) => p.optional);

  const out: string[] = [
    '# Example Co',
    '',
    '> Software development company building custom software, SaaS and mobile apps for mid-size companies.',
    '',
  ];

  for (const section of ORDER) {
    const items = core.filter((p) => p.section === section);
    if (items.length === 0) continue;
    out.push(`## ${section}`, '', ...items.map(line), '');
  }

  if (optional.length > 0) {
    out.push('## Optional', '', ...optional.map(line), '');
  }

  return new Response(out.join('\n'), {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}

Point to it from robots.txt with a comment so people can find it too. Crawlers ignore comments, so this is a note, not a directive:

# Plain-language site summary for language models (llmstxt.org)
# LLM-Content: https://example.com/llms.txt

Check it in CI

Generating the file stops it drifting from the sitemap. It doesn't stop either one linking to a page that now redirects or returns a 404. A small check against the preview deploy catches that:

// scripts/check-llms.mjs
const base = process.env.PREVIEW_URL;
const txt = await (await fetch(`${base}/llms.txt`)).text();
const urls = [...txt.matchAll(/\]\((https?:\/\/[^)]+)\)/g)].map((m) => m[1]);

let failed = 0;
for (const url of urls) {
  const res = await fetch(url.replace(/^https?:\/\/[^/]+/, base), { redirect: 'manual' });
  if (res.status !== 200) {
    console.error(`${res.status}  ${url}`);
    failed++;
  }
}
console.log(`${urls.length - failed}/${urls.length} links return 200`);
process.exit(failed ? 1 : 0);

redirect: 'manual' matters: a 301 is a broken entry in a file whose whole job is to point at the right page.

Writing the summaries

The generator handles structure. The one-line summaries are still writing, and they're what a model reads. A few rules that have worked for us:

• Say what the page is for, not what it ranks for. "Multi-tenant SaaS products, from MVP to scale" beats a string of keywords.
• Keep it to one line per page. If a page needs a paragraph to describe, it's probably two pages.
• Put pages you'd be happy to be quoted from in the main sections, and legal or utility pages under Optional.

Is anyone reading it?

You won't know unless you look. Filter your access logs or edge logs for /llms.txt and group by user agent. If GPTBot, ClaudeBot or PerplexityBot never request it, that's worth knowing before you spend more time on it. Either way, the pages it links to still need to be crawlable and worth citing on their own.

We build this into the sites we work on as part of generative engine optimization: making sure AI search tools can find, read and quote the pages that matter.

Have you seen a crawler actually fetch your llms.txt? We'd like to compare logs.

That's the short version of our full guide. Here are the parts worth knowing before your first vendor call.

Decide what you are buying first

A fixed-scope project, a dedicated team and staff augmentation are different purchases. Each one needs a different kind of supplier, so the shortlist goes wrong when this isn't settled up front.

Three tests that matter more than a portfolio

1. How they work on your problem. Give them a slice of your real requirement and watch how they question it.
2. What the quote assumes. Two similar prices can cover very different scope. Ask every vendor to write their assumptions down.
3. Who does the work. Meet the people who will actually build it, not only the sales team.

Two more things to get right

• Read reviews for the criticism. What a past client would have liked done differently tells you what working with the vendor is like.
• Own your code from day one. The repository, hosting and store accounts should be in your organization's name.

The full guide covers where the vendor is based and what that changes, eight questions to put to every vendor in writing, and why the cheapest quote is often the one that underestimated the work.

Read the full guide on the Redlio Labs blog