Überblick

Ein Webhook ist die Rückmeldung von PayPal an Kyvento: Immer wenn bei PayPal etwas passiert, das Kyvento wissen muss – eine Zahlung ist eingegangen, ein Betrag wurde erstattet, PayPal bucht eine Zahlung zurück oder ein Kunde eröffnet einen Konflikt (Dispute) –, schickt PayPal 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 Ihrer PayPal-App ein und übertragen anschließend die von PayPal erzeugte Webhook-ID zurück nach Kyvento.

Voraussetzungen

• Ein PayPal-Geschäftskonto und Zugang zum PayPal Developer Dashboard (developer.paypal.com).
• PayPal ist in Kyvento eingerichtet (Client-ID und Secret hinterlegt) – Einstellungen → Zahlungen → PayPal.
• In Kyvento die Berechtigung, Einstellungen zu verwalten (z. B. Systemrolle „Administrator" oder „Vollzugriff").
• Sie wissen, ob Sie PayPal in Kyvento im Live- oder im Sandbox-Modus betreiben.

Schritt 1: Webhook-URL aus Kyvento kopieren

1. Öffnen Sie in Kyvento Einstellungen → Zahlungen → PayPal.
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/paypal/123.
3. Klicken Sie auf das Kopier-Symbol, um die vollständige URL in die Zwischenablage zu übernehmen.

Schritt 2: Die richtige App im PayPal Developer Dashboard öffnen

1. Melden Sie sich unter developer.paypal.com an und öffnen Sie Apps & Credentials.
2. Schalten Sie oben auf die passende Umgebung um: Live oder Sandbox – dieselbe, die Sie in Kyvento verwenden.
3. Öffnen Sie die App, deren Client-ID und Secret Sie in Kyvento hinterlegt haben.

Schritt 3: Den Webhook anlegen und Ereignisse auswählen

1. Scrollen Sie in der App zum Abschnitt „Webhooks" und klicken Sie auf „Add Webhook".
2. Fügen Sie unter „Webhook URL" die in Schritt 1 kopierte Kyvento-URL ein.
3. Wählen Sie bei „Event types" die folgenden Ereignisse aus. Kyvento verarbeitet ausschließlich diese – ein fehlendes Ereignis bedeutet, dass die zugehörige Aktion in Kyvento nie ankommt:

• PAYMENT.CAPTURE.COMPLETED – Zahlung erfolgreich eingegangen (Rechnung wird auf „bezahlt" gesetzt)
• PAYMENT.CAPTURE.DENIED – Zahlung abgelehnt/fehlgeschlagen
• PAYMENT.CAPTURE.REFUNDED – Betrag wurde erstattet
• PAYMENT.CAPTURE.REVERSED – erzwungene Rückbuchung (z. B. durch die Bank), auch ohne formalen Konflikt
• CUSTOMER.DISPUTE.CREATED – Kunde eröffnet einen Konflikt/Käuferschutzfall
• CUSTOMER.DISPUTE.RESOLVED – Konflikt abgeschlossen (zu Ihren Gunsten oder nicht)

Die sechs Ereignisse oben sind verpflichtend für eine vollständige Verbuchung. Zusätzlich können Sie optional VAULT.PAYMENT-TOKEN.CREATED und VAULT.PAYMENT-TOKEN.DELETED aktivieren – sie liefern nur ein zusätzliches Kontrollsignal für gespeicherte Zahlungsmethoden und sind für Zahlungen, Erstattungen und Konflikte nicht erforderlich.

4. Speichern Sie den Webhook mit „Save".

Falls Ihnen die Einzelauswahl zu kleinteilig ist, funktioniert auch „All events" – Kyvento ignoriert dann einfach alles, was nicht in der Liste oben steht. Die gezielte Auswahl hält das Ereignis-Protokoll jedoch übersichtlicher.

Schritt 4: Die Webhook-ID zurück nach Kyvento übertragen

Damit Kyvento sicher sein kann, dass eine Nachricht wirklich von Ihrer PayPal-App stammt, prüft es jede Zustellung anhand der Webhook-ID. Ohne diese ID lehnt Kyvento alle Ereignisse ab.

1. Nach dem Speichern zeigt PayPal die neu erzeugte Webhook-ID an (eine Zeichenfolge wie 5GP028356R811364S). Kopieren Sie diese ID.
2. Wechseln Sie zurück nach Kyvento: Einstellungen → Zahlungen → PayPal.
3. Fügen Sie die kopierte ID in das Feld „Webhook ID" ein.
4. Speichern Sie die Einstellungen.

Erfolgskontrolle

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

1. Öffnen Sie in der PayPal-App den angelegten Webhook und nutzen Sie – sofern verfügbar – die Funktion zum Senden eines Test-/Mock-Ereignisses (z. B. PAYMENT.CAPTURE.COMPLETED).
2. Im Ereignis-Protokoll des Webhooks muss die Zustellung mit dem Status HTTP 200 erscheinen. Der Status 200 bestätigt dabei nur, dass Kyvento die Zustellung angenommen hat – die Echtheitsprüfung anhand der Webhook-ID läuft unmittelbar danach.

Entscheidend ist deshalb die echte Gegenprobe: Lösen Sie eine Testzahlung aus – sie erscheint in Kyvento als „bezahlt". Erstatten Sie diese Zahlung anschließend direkt in PayPal; in Kyvento erscheint die zugehörige Zahlung daraufhin als „Erstattet" (in der Zahlungsübersicht der Rechnung).

Wenn es nicht klappt

• Status 403 im PayPal-Protokoll: In Kyvento fehlt die Webhook-ID (oder Client-ID/Secret) – Schritt 4 wurde noch nicht abgeschlossen. Tragen Sie die Webhook-ID in das Feld „Webhook ID" ein und speichern Sie.
• Zustellungen zeigen Status 200, aber in Kyvento kommt nichts an: Die hinterlegte Webhook-ID passt nicht zur sendenden App. Häufigste Ursache: Die ID stammt aus der falschen Umgebung (Live statt Sandbox oder umgekehrt) oder aus einer anderen App. Kyvento nimmt die Zustellung zwar an, verwirft sie aber bei der anschließenden Echtheitsprüfung. Übertragen Sie die Webhook-ID aus genau der App, deren Client-ID in Kyvento hinterlegt ist.
• Status 404: Die Webhook-URL ist unvollständig – meist fehlt die Konto-Nummer am Ende. Kopieren Sie die URL erneut aus der Karte „Webhook-URL".
• Erstattungen/Konflikte kommen nicht an, Zahlungen aber schon: In der Ereignis-Auswahl fehlen die PAYMENT.CAPTURE.REFUNDED-/CUSTOMER.DISPUTE.*-Typen. Ergänzen Sie sie in der PayPal-App.

Nächste Schritte

• Stripe-Webhook einrichten – siehe „Webhook-Einrichtung bei Stripe"
• PayPal als Zahlungsmethode aktivieren – siehe „PayPal-Integration"
• Eine direkt in PayPal ausgelöste Erstattung von Hand nachtragen – siehe „PayPal-Erstattung manuell in Kyvento nachtragen"