Stripe Webhook (Zahlungs-Events)

Stripe sendet bei jedem Zahlungsereignis einen HTTP-POST-Request an den Endpunkt /api/stripe/webhook. Replix verifiziert die Signatur mit dem Webhook-Secret, prüft Idempotenz (jedes Event wird nur einmal verarbeitet) und aktualisiert den Abonnement-Status in der Datenbank.

Folgende Events werden verarbeitet: 1) checkout.session.completed — Plan und Abo aktiviert, Trial gestartet, Empfehlungs-Belohnungen verarbeitet. 2) customer.subscription.updated — Status-Mapping (active, trialing, past_due, canceled), Plan-Auflösung. 3) customer.subscription.deleted — Nachfrist gesetzt (7 Tage bei Trial, 30 Tage bei bezahltem Abo). 4) invoice.payment_failed — Status auf past_due, Zahlungsausfall-E-Mail. 5) invoice.paid — Wiederherstellung nach past_due, Bestätigungsmail. 6) customer.subscription.trial_will_end — Trial-Erinnerung 3 Tage vor Ablauf.

Bei Zahlungsausfall (invoice.payment_failed) wird der Status auf 'past_due' gesetzt und das Datum past_due_since erfasst. Stripe versucht die Zahlung automatisch erneut. Am 6. Tag erhältst du eine Warnung-E-Mail, am 7. Tag wird der Zugang gesperrt. Sobald die Zahlung erfolgreich ist (invoice.paid), wird der Zugang sofort wiederhergestellt.

Bei einer Kündigung über das Stripe-Portal wird das Event customer.subscription.deleted ausgelöst. Replix setzt eine Nachfrist: 30 Tage für bezahlte Abos (du behältst Zugang bis zum bezahlten Zeitraum-Ende), 7 Tage für Trial-Nutzer. Nach Ablauf der Nachfrist wird der Plan auf Basic zurückgesetzt.

Jedes Stripe-Event hat eine eindeutige Event-ID. Replix speichert verarbeitete Events in der Tabelle processed_webhook_events. Bevor ein Event verarbeitet wird, wird versucht, die ID einzufügen — schlägt dies wegen Unique-Constraint fehl, wurde das Event bereits verarbeitet und wird übersprungen. So wird verhindert, dass Stripe-Retries zu doppelter Verarbeitung führen.