Next.js-Abonnement-Abrechnung: Webhooks, die funktionieren
Die meisten Tutorials zur Abonnement-Abrechnung bleiben beim Happy Path stehen: Checkout-Session erstellen, Browser weiterleiten, fertig. Das funktioniert in einer Demo. Es scheitert beim ersten Mal, wenn ein Kunde den Tab mitten in der Zahlung schließt, ein Anbieter ein Ereignis erneut sendet oder ein Test zweimal auslöst. Produktive Abrechnung lebt in den Teilen, die diese Tutorials überspringen. Dies ist der Vertrag hinter den von Uncorne generierten Apps — fünf Zahlungsanbieter hinter einer einzigen Prüf- und Berechtigungsebene — und die Begründung für jede Regel.

Der Browser ist keine Wahrheitsquelle
Eine erfolgreiche Weiterleitung ist ein Hinweis, keine Tatsache. Der Kunde kann nach der Zahlung den Tab schließen, bevor Ihre Erfolgsseite geladen ist. Ein Webhook kann vor der Weiterleitung eintreffen, zweimal eintreffen oder gar nicht, wenn die Signaturprüfung fehlschlägt. Behandeln Sie die Weiterleitung als rein kosmetischen Dankesbildschirm und sonst nichts.
Ihre Datenbank ist die einzige Wahrheitsquelle, und genau eine Sache darf den Abonnementstatus hineinschreiben: ein verifizierter Webhook des Anbieters. Alles andere — die Erfolgsseite, ein Abruf der Anbieter-API, die Notiz eines Support-Mitarbeiters — liest nur aus dieser Datenbank. Wenn Sie das umgekehrt machen, gewähren Sie irgendwann jemandem Zugriff, der nie bezahlt hat, oder entziehen ihn jemandem, der bezahlt hat. Die offizielle Stripe-Übersicht zu Abonnements listet die Lebenszyklus-Ereignisse, die es zu behandeln gilt; die praktische Regel lautet: weniger Ereignisse behandeln, jedes richtig behandeln und den Rest laut statt still ignorieren.
Den Prüfvertrag präzise formulieren
Die Signaturprüfung muss das Erste sein, was Ihre Route tut — bevor ein Body geparst, bevor die Datenbank berührt und bevor etwas protokolliert wird, das Kundendaten enthält. Der Vertrag ist es wert, aufgeschrieben zu werden, denn ihn umgekehrt zu machen ist ein Sicherheitsfehler, keine Geschmacksfrage:
- Fehlende, ungültige oder fehlerhafte Signatur → Fehler werfen. Die Route antwortet 400 und schreibt nichts.
- Gültig signiertes Ereignis, das keiner Behandlung bedarf → leeres Ergebnis und 200 mit ignored-Flag zurückgeben.
- Bereits gesehene Ereignis-ID → vor jedem Schreiben überspringen.
- Gültiges, neues, zu behandelndes Ereignis → schreiben und die Ereignis-ID in derselben Transaktion erfassen.
Eine frühere Version der Uncorne-Adapter gab bei Prüffehlern eine leere Liste zurück. Das bedeutete, dass eine gefälschte Anfrage mit 200 bestätigt wurde. Wir haben geändert, dass ein Prüffehler eine Ausnahme wirft, bevor die Route irgendetwas bestätigen kann. Gehen Sie diesen Kompromiss nicht ein — ein 200 ist ein Versprechen, und Sie sollten es erst geben, nachdem Sie die Signatur wie im Stripe-Leitfaden zu Webhook-Signaturen beschrieben geprüft haben.
export async function POST(req: Request) {
const raw = await req.text(); // gegen den ROH-Body prüfen
let event: ProviderEvent;
try {
event = verifyAndParse(raw, req.headers); // wirft bei schlechter Signatur
} catch {
return new Response("invalid signature", { status: 400 });
}
if (shouldIgnore(event)) {
return json({ ignored: true, handled: [] });
}
const fresh = await markSeen(event.id); // atomares Insert, false bei Duplikat
if (!fresh) return json({ ignored: true, duplicate: true });
await applyPlanChange(event); // schreibt customer -> plan
return json({ handled: [event.type] });
}Prüfen Sie gegen den rohen Request-Body, niemals gegen ein neu serialisiertes Objekt. JSON-Schlüsselreihenfolge und Leerzeichen sind über Anbieter und SDK-Versionen hinweg nicht stabil, und erneutes Serialisieren ist ein klassischer Weg, eine völlig korrekte Signatur zu ungültig zu machen. Lesen Sie den Body einmal mit req.text(), übergeben Sie exakt diese Bytes dem Prüfer und parsen Sie erst danach zu einem Objekt.

Idempotenz ist keine Option
Anbieter senden erneut. Ein Webhook, der einen Tarif freischaltet, wird erneut zugestellt, wenn Ihr Endpoint langsam ist, einen 500 zurückgibt oder abbricht. Ohne Deduplizierung kann die zweite Zustellung das Kontingent eines Benutzers zurücksetzen, ein Abonnement zweimal verlängern oder eine zweite Willkommens-E-Mail senden. Erstellen Sie eine Tabelle, die jede verarbeitete Ereignis-ID erfasst:
create table webhook_events (
provider text not null,
event_id text not null,
type text not null,
received_at timestamptz not null default now(),
primary key (provider, event_id)
);Das Insert ist das Tor: Verwenden Sie ein atomares Insert, das bei Konflikt false zurückgibt, und fahren Sie nur fort, wenn es true zurückgibt. Bei Supabase ist dies ein Upsert mit onConflict und einem Konfliktzweig; im lokalen SQLite-Pfad ist es ein INSERT ... ON CONFLICT DO NOTHING gefolgt von einer Prüfung der geänderten Zeilen. Führen Sie die Deduplizierung nach Möglichkeit in derselben Transaktion wie das Tarif-Schreiben aus, damit ein Absturz nicht einen erfassten Ereignisdatensatz bei unverändertem Tarif hinterlässt. Bewahren Sie die Zeilen mindestens so lange auf wie das Wiederholungsfenster des Anbieters — Stripe versucht bis zu drei Tage, daher sind 30 Tage Aufbewahrung ein komfortabler Spielraum.
Berechtigungen auf dem Server prüfen, nie in der Oberfläche
Ein Button zu verstecken ist keine Zugriffskontrolle. Lesen Sie den Tarif auf jeder geschützten Route aus der Sitzung oder der Datenbank und treffen Sie dort die Entscheidung. Im App Router bedeutet dies einen Route Handler oder eine Server Action, die das Sitzungs-Cookie mit cookies() liest und die Berechtigung nachschlägt — keine Client-Komponente, die ein Prop prüft. Wenn der Tarif inaktiv ist, gibt der KI-Endpoint 402 zurück, selbst wenn jemand das DOM in den Devtools bearbeitet oder die API direkt mit curl aufruft.
export async function POST(req: Request) {
const session = await getSession();
if (!session?.user) return new Response("unauthorized", { status: 401 });
const entitlement = await getEntitlement(session.user.id);
if (!entitlement.active) {
return Response.json({ code: "no_entitlement" }, { status: 402 });
}
return streamAnswer(req, session.user.id);
}Das Gleiche gilt für Server Actions und Mutations: Autorisieren Sie innerhalb der Action, nicht in der Komponente, die das Formular rendert. Clientseitige Prüfungen dienen der Bedienbarkeit, serverseitige der Sicherheit. Wenn Sie nur eine machen, machen Sie die serverseitige. Eine nützliche Gewohnheit ist, zuerst die Serverprüfung zu schreiben und die UI als Abbild einer bereits getroffenen Entscheidung zu behandeln.

402 und 429 sind verschiedene Antworten
Zwei Fehlerfälle werden ständig verwechselt. Ein 402 bedeutet: keine Berechtigung — keine gültige Lizenz, kein aktives Abonnement, keine verifizierte E-Mail-Zuordnung. Ein 429 bedeutet: Der Kunde ist berechtigt, hat aber ein Nutzungskontingent erschöpft. Sie zu vermischen macht Dashboards irreführend und Support schmerzhaft, denn die Lösung für das eine ist „Tarif kaufen", die für das andere „auf die Rücksetzung warten".
| Status | Code | Bedeutung | Was der Client tun sollte | | --- | --- | --- | --- | | 402 | no_entitlement | Keine aktive Lizenz oder kein Abonnement | Abrechnungsportal öffnen | | 402 | preview_limit_reached | Anonymes Vorschau-Kontingent aufgebraucht | Zur Registrierung auffordern | | 429 | quota_exceeded | Tägliches KI-Kontingent aufgebraucht | Rücksetzzeit anzeigen | | 400 | invalid_signature | Webhook-Signaturprüfung fehlgeschlagen | Nichts — nur serverseitig |
Der Abonnementstatus ist nicht dasselbe wie Nutzungsgrenzen. Der KI-Endpoint hat ein eigenes tägliches Kontingent pro Benutzer (AI_MESSAGES_PER_DAY, Standard 50), gestützt auf einen Supabase-RPC oder die lokale SQLite-Tabelle ai_usage. Ist es erschöpft, geben Sie 429 mit einem X-AI-Quota-Reset-Header und einem ehrlichen Retry-After in Sekunden zurück, berechnet aus dem tatsächlichen Rücksetz-Zeitstempel — nicht einem fest codierten 86400. Ein falscher Wiederholungshinweis ist schlimmer als keiner: Er gewöhnt Clients daran, den Header zu ignorieren, und zwingt das Support-Team zum Raten.
Ein Checkout-Vertrag, fünf Anbieter
Uncorne liefert Adapter für Waffo, Stripe, Creem, PayPal und Lemon Squeezy hinter einer einzigen Schnittstelle. Jeder Adapter mappt die Ereignisse des Anbieters auf ein kleines internes Vokabular — activated, renewed, cancelled, past due — und die Berechtigungsebene versteht nur dieses Vokabular. Ein Anbieterwechsel ist damit eine Konfigurationsänderung plus einer Webhook-URL-Aktualisierung, keine Neuschreibung Ihres Produktcodes. Die Stripe Checkout Sessions API ist eine gute Referenz für die zu normalisierenden Felder: Kunden-ID, Abonnement-ID, Preis-ID und aktuelles Periodenende.
Der Kompromiss ist ehrlich: Ein gemeinsamer Vertrag ist ein kleinster gemeinsamer Nenner. Anbieterspezifische Funktionen wie verbrauchsbasierte Abrechnung oder die Steuerabwicklung eines Merchant of Record benötigen einen Ausweg. Behalten Sie eine Adaptermethode für anbieterspezifische Daten und dokumentieren Sie, dass sie bewusst nicht portierbar ist, damit niemand annimmt, die Abstraktion sei Magie.

Erstattungen, Kündigungen und was „aktiv" wirklich bedeutet
Ein Abonnement kann in einem System aktiv und in einem anderen erstattet sein. Hören Sie neben den Abonnement-Ereignissen auch auf Erstattungs- und Zahlungsstreit-Ereignisse und behandeln Sie eine vollständige Erstattung als sofortigen Widerruf statt bis zum Periodenende zu warten. Bei Kündigungen bevorzugen Sie cancel_at_period_end, damit der Kunde während der bezahlten Periode Zugriff behält und Sie ein Support-Ticket über Datenverlust am ersten Tag vermeiden.
Speichern Sie den Rohstatus des Anbieters neben Ihrer normalisierten Berechtigung und leiten Sie „aktiv" niemals aus einem Boolean ab, der einmal bei der Registrierung gesetzt wurde. Berechnen Sie ihn beim Lesen aus dem zuletzt angewendeten Ereignis neu. Diese eine Änderung behebt eine überraschende Klasse von Fehlern, bei denen der Tarif in der Datenbank korrekt aussieht, im Produkt aber falsch ist.
Prüfen Sie die Sicherheits-Invariante offline
Sie brauchen keine fünf Sandbox-Konten, um den Vertrag zu validieren. Uncorne enthält eine Offline-Signatursonde — npm run probe:webhook — die vier Bodies an einen laufenden Server sendet: gültig signiert, Signatur fehlt, Signatur beschädigt und fehlerhaftes JSON. Sie prüft die Statuscodes aus der Tabelle oben, sodass ein Regression, der ein gefälschtes Ereignis mit 200 bestätigt, in der CI fehlschlägt. Der Stripe-Webhooks-Leitfaden dokumentiert die Ereignistypen, die eine echte Sandbox zustellt; nutzen Sie diese Liste für Ihre End-to-End-Fälle.
Die vier Schichten, in steigender Realitätsnähe:
- Unit-Tests der Prüffunktion mit festen Fixtures.
- Die Offline-Sonde gegen einen laufenden Entwicklungsserver — keine Zugangsdaten nötig.
- Sandbox-End-to-End-Läufe mit den Testschlüsseln jedes Anbieters, einschließlich einer echten Wiederholung.
- Ein kleiner Canary nach dem Deployment: ein Abonnement mit geringem Betrag, sofort erstattet.
Schicht 1 und 2 gehören in die CI und sollten schnell sein. Schicht 3 und 4 sind ein Gate vor dem Launch. Die Offline-Schicht zu überspringen ist der häufigste Fehler: Sie ist die einzige, die den Fehler „bei Misserfolg 200 zurückgeben" ohne Abhängigkeit von einem externen Dienst erkennt.

Fehlerfälle, die es zu antizipieren gilt
Einige Situationen sind selten genug, um vergessen zu werden, und häufig genug, um zu schaden. Ein Verlängerungs-Webhook kommt verspätet, nachdem Ihr Cron den Zugriff bereits widerrufen hat — berechnen Sie die Berechtigung aus dem aktuellen Anbieterzustand neu, statt Ereignisse isoliert anzuwenden. Ein Kunde führt ein Upgrade durch und zwei Abonnement-Ereignisse treffen in falscher Reihenfolge ein — speichern Sie den Zeitstempel des Periodenendes und ignorieren Sie Ereignisse, die älter sind als das bereits angewendete. Ein Webhook ist korrekt signiert, verweist aber auf eine Kunden-ID, die Sie noch nicht haben — queuen Sie ihn und versuchen Sie es nach der Benutzererstellung erneut, statt ihn zu verwerfen.
Beobachtbarkeit ist hier wichtig. Protokollieren Sie Ereignis-ID, Typ und die getroffene Entscheidung (handled, ignored, duplicate, failed) mit einer gehashten Kunden-ID. Protokollieren Sie nicht den Roh-Body; er enthält personenbezogene Daten und möglicherweise ein Zahlungsmittel-Token. Wenn ein Kunde sagt „ich habe bezahlt, bin aber immer noch ausgesperrt", sollten Sie mit einer Abfrage beantworten können, welche Ereignisse eingetroffen sind und was Sie damit gemacht haben.
Kurze Checkliste vor dem Launch
- Die Prüfung gegen den Roh-Body wirft bei Misserfolg eine Ausnahme und gibt nie 200 zurück.
- Jede verarbeitete Ereignis-ID wird vor dem Tarif-Schreiben atomar erfasst.
- Geschützte Routes lesen die Berechtigung auf dem Server; keine reinen Client-Gates.
- 402 und 429 tragen stabile maschinenlesbare Codes und ehrliche Wiederholungs-Header.
- Die Offline-Sonde läuft in der CI bei jedem Pull Request.
- Vor dem Launch mindestens ein Sandbox-End-to-End-Lauf pro Anbieter.
Den vollständigen Ablauf zum Erstellen von Produkten und der Checkout-Route finden Sie in Stripe-Abonnements zu Next.js hinzufügen. Wo die Abrechnung in einem Starter sitzt, zeigt Was Sie in einem Next.js-SaaS-Boilerplate mit Stripe und Auth prüfen sollten.
Abonnement-Abrechnung ist nicht schwer, weil die APIs schwer sind. Sie ist es, weil die Randfälle unsichtbar bleiben, bis ein echter Kunde sie trifft. Schreiben Sie den Vertrag auf, testen Sie die Invariante offline, und lassen Sie den Webhook — nicht den Browser — entscheiden, wer Zugriff erhält.
FAQ
Reicht eine Browser-Weiterleitung aus, um bezahlten Zugriff zu gewähren?+
Nein. Eine Weiterleitung ist ein Hinweis, kein Zahlungsnachweis. Nur ein verifizierter Webhook sollte den Abonnementstatus in Ihre Datenbank schreiben; alles andere, einschließlich der Erfolgsseite, liest nur daraus. Das verhindert Zugriff für Benutzer, die vor der Zahlung den Tab schließen oder einen Callback erneut abspielen.
Wie mache ich einen Webhook idempotent?+
Speichern Sie die Anbieter-Ereignis-ID in einer webhook_events-Tabelle mit Primärschlüssel auf (provider, event_id) und führen Sie vor jedem Schreiben eines Tarifs oder einer Lizenz ein atomares Insert aus. Die Prüfung läuft zuerst; nur verifizierte, unbehandelte Ereignisse erreichen die Deduplizierung. Stripe versucht bis zu drei Tage, bewahren Sie Zeilen mindestens 30 Tage auf.
Was ist der Unterschied zwischen 402 und 429 in einer Abo-App?+
402 bedeutet: keine Berechtigung — keine gültige Lizenz, kein aktives Abonnement, keine verifizierte E-Mail-Zuordnung. 429 bedeutet: Der Kunde ist berechtigt, hat aber das tägliche KI-Kontingent erschöpft. Ein erschöpftes Vorschau-Kontingent ist ein separates 402 mit dem Code preview_limit_reached. Ein 402 löst man durch Tarifkauf, ein 429 durch Warten auf die Rücksetzung.
Wie sollte ich Webhook-Signaturen in Next.js prüfen?+
Lesen Sie den rohen Request-Body einmal mit req.text() und übergeben Sie exakt diese Bytes dem Prüfer, bevor Sie ihn zu einem Objekt parsen. Werfen Sie bei fehlender, ungültiger oder fehlerhafter Signatur eine Ausnahme, damit die Route 400 antwortet und nichts schreibt. Ein vorheriges Neu-Serialisieren von JSON kann eine korrekte Signatur ungültig machen, weil Schlüsselreihenfolge und Leerzeichen variieren.
Kann ich Abrechnungen ohne Sandbox-Konten testen?+
Sie können den gemeinsamen Prüfvertrag offline mit npm run probe:webhook validieren, das gültige, fehlende, beschädigte und fehlerhafte Bodies an einen laufenden Server sendet und die Statuscodes prüft. Der echte Checkout-Ablauf jedes Gateways benötigt vor dem Launch weiterhin eigene Sandbox-Zugangsdaten; die vier Schichten finden Sie in docs/payment-testing.md.