Webhook-Einrichtung bei Stripe

Überblick

Ein Webhook ist die Rückmeldung von Stripe an Kyvento: Immer wenn bei Stripe etwas passiert, das Kyvento wissen muss – eine Zahlung ist final gebucht, ein Betrag wurde erstattet, ein Kunde eröffnet einen Zahlungsstreit (Dispute) oder eine SEPA-Lastschrift platzt –, schickt Stripe eine Nachricht an eine feste Adresse in Kyvento. Ohne diesen Rückkanal sieht Kyvento nur die unmittelbare Zahlung, aber keine dieser nachgelagerten Ereignisse. Die Folge: Rechnungen bleiben fälschlich auf „bezahlt", obwohl das Geld längst zurückgeflossen ist. Dieser Artikel zeigt Ihnen Schritt für Schritt, wie Sie den Webhook einrichten – das ist ein Zwei-Wege-Setup: Sie tragen die Kyvento-Webhook-URL in Stripe ein und übertragen anschließend das von Stripe erzeugte Signing Secret zurück nach Kyvento.

Voraussetzungen

• Ein eigener Stripe-Account mit Zugang zum Stripe-Dashboard (dashboard.stripe.com).
• Stripe ist in Kyvento über „Manuelle API-Keys" eingerichtet (Einstellungen → Zahlungen → Stripe).
• In Kyvento die Berechtigung, Einstellungen zu verwalten (z. B. Systemrolle „Administrator" oder „Vollzugriff").
• Achten Sie auf den Modus: Test- und Live-Modus haben in Stripe getrennte Webhooks und getrennte Signing Secrets. Richten Sie den Webhook in dem Modus ein, in dem Sie Stripe auch in Kyvento betreiben.

Schritt 1: Webhook-URL aus Kyvento kopieren

1. Öffnen Sie in Kyvento Einstellungen → Zahlungen → Stripe.
2. Suchen Sie die Karte „Webhook-URL". Dort steht Ihre persönliche, kontogebundene Adresse – sie endet auf Ihre Kyvento-Konto-Nummer und sieht etwa so aus: https://app.kyvento.com/api/webhooks/stripe/123.
3. Klicken Sie auf das Kopier-Symbol, um die vollständige URL in die Zwischenablage zu übernehmen.

Schritt 2: Den Webhook-Endpoint in Stripe anlegen

1. Melden Sie sich im Stripe-Dashboard an und wählen Sie oben rechts den passenden Modus (Test oder Live).
2. Öffnen Sie Developers → Webhooks und klicken Sie auf „Add endpoint" (Endpoint hinzufügen).
3. Fügen Sie unter „Endpoint URL" die in Schritt 1 kopierte Kyvento-URL ein.
4. Optional können Sie eine Beschreibung vergeben, z. B. „Kyvento".

Schritt 3: Die richtigen Ereignisse auswählen

Klicken Sie auf „Select events" und wählen Sie genau diese Ereignistypen aus. Kyvento verarbeitet ausschließlich die folgenden – ein fehlendes Ereignis bedeutet, dass die zugehörige Aktion in Kyvento nie ankommt:

• payment_intent.succeeded – Zahlung erfolgreich abgeschlossen (Rechnung wird auf „bezahlt" gesetzt)
• payment_intent.processing – Zahlung in Bearbeitung (z. B. SEPA-Erstzahlung noch nicht final)
• payment_intent.payment_failed – Zahlung fehlgeschlagen
• payment_intent.requires_action – zusätzliche Bestätigung nötig (3-D-Secure/SCA)
• charge.refunded – Betrag wurde erstattet (auch bei geplatzter SEPA-Lastschrift)
• charge.dispute.created – Kunde eröffnet einen Zahlungsstreit (Chargeback)
• charge.dispute.closed – Zahlungsstreit abgeschlossen (gewonnen/verloren)
• payment_method.updated – aktualisierte Kartendaten (automatische Kartenverlängerung)
• setup_intent.succeeded – Zahlungsmethode erfolgreich hinterlegt
• setup_intent.setup_failed – Hinterlegen der Zahlungsmethode fehlgeschlagen

Sie müssen keine weiteren Ereignisse aktivieren. Zusätzliche Typen schaden zwar nicht, erzeugen aber unnötige Zustellungen, die Kyvento ignoriert.

5. Bestätigen Sie die Auswahl und klicken Sie auf „Add endpoint", um den Webhook zu speichern.

Schritt 4: Das Signing Secret zurück nach Kyvento übertragen

Damit Kyvento sicher sein kann, dass eine Nachricht wirklich von Ihrem Stripe-Account stammt, prüft es jede Zustellung mit einem geheimen Schlüssel – dem Signing Secret. Ohne dieses Secret lehnt Kyvento alle Ereignisse ab.

1. Öffnen Sie in Stripe den soeben angelegten Endpoint.
2. Klicken Sie im Abschnitt „Signing secret" auf „Reveal" und kopieren Sie den Wert. Er beginnt mit whsec_.
3. Wechseln Sie zurück nach Kyvento: Einstellungen → Zahlungen → Stripe.
4. Öffnen Sie den Bereich „Manuelle API-Keys" (Schaltfläche „Manuell konfigurieren").
5. Fügen Sie den kopierten Wert in das Feld „Webhook Secret" ein.
6. Speichern Sie die Einstellungen.

Erfolgskontrolle

Prüfen Sie zum Abschluss, ob die Verbindung wirklich funktioniert:

1. Öffnen Sie in Stripe den Endpoint und klicken Sie auf „Send test webhook".
2. Wählen Sie das Ereignis payment_intent.succeeded und senden Sie es.
3. Im Ereignis-Protokoll des Endpoints muss die Zustellung mit dem Status HTTP 200 erscheinen.

Zusätzlich als echte Gegenprobe: Lösen Sie eine Testzahlung aus – sie erscheint in Kyvento als „bezahlt". Erstatten Sie diese Zahlung anschließend im Stripe-Dashboard; in Kyvento erscheint die zugehörige Zahlung daraufhin als „Erstattet" (in der Zahlungsübersicht der Rechnung).

Wenn es nicht klappt

• Status 400 im Stripe-Protokoll: Das Signing Secret in Kyvento passt nicht zum Endpoint. Prüfen Sie, ob Sie den Wert aus dem richtigen Modus (Test/Live) kopiert und vollständig eingefügt haben.
• Status 403: In Kyvento ist noch kein Signing Secret hinterlegt – Schritt 4 wurde noch nicht abgeschlossen. Tragen Sie den whsec_…-Wert in das Feld „Webhook Secret" ein und speichern Sie.
• Status 404: Die Endpoint-URL ist unvollständig – meist fehlt die Konto-Nummer am Ende. Kopieren Sie die URL erneut aus der Karte „Webhook-URL".
• Erstattungen/Disputes kommen nicht an, Zahlungen aber schon: In der Ereignis-Auswahl fehlen die charge.*-Typen. Ergänzen Sie sie im Stripe-Endpoint.

Nächste Schritte

• PayPal-Webhook einrichten – siehe „Webhook-Einrichtung bei PayPal"
• Kreditkartenzahlungen mit Stripe anbinden – siehe „Kreditkartenzahlungen akzeptieren"
• Erstattungen und Rückbuchungen in der Buchhaltung nachvollziehen – siehe „Gutschriften und Stornierungen"