Überblick

Webhooks drehen den Informationsfluss um: Statt Ihre Systeme regelmäßig nach Änderungen fragen zu lassen, meldet Kyvento Ereignisse – neue Abos, bezahlte Rechnungen, fehlgeschlagene Zahlungen – sofort per HTTP-POST an Ihre URL. Dieser Artikel zeigt Einrichtung, Ereignis-Auswahl und Signaturprüfung.

Endpoint anlegen

Öffnen Sie Einstellungen → „Webhooks" (Gruppe „Integration") und klicken Sie auf „+ Neuer Endpoint":

• „Name (optional)": etwa „ERP-Integration" – zur Wiedererkennung in der Liste.
• „Endpoint-URL": die HTTPS-Adresse Ihres Empfängers. Private und interne Netzwerkadressen lehnt Kyvento aus Sicherheitsgründen ab.
• „Authentifizierung & Headers (optional)": bei Bedarf Basic-Auth-Zugangsdaten und eigene HTTP-Header, die Kyvento bei jeder Zustellung mitsendet.
• „Ereignisse": per Checkbox die Event-Typen, die dieser Endpoint erhalten soll – oder „Alle auswählen".

Nach dem Erstellen zeigt Kyvento das Signing-Secret (Präfix whsec_) einmalig an – hinterlegen Sie es sicher in Ihrer Empfänger-Anwendung, Sie brauchen es für die Signaturprüfung.

Die wichtigsten Ereignis-Gruppen

• customer.* – Kunden erstellt, geändert, gelöscht, Zahlungsmethode aktualisiert
• subscription.* – Abo erstellt, verlängert, pausiert, gekündigt, Testphase umgewandelt oder endet bald, Tarif gewechselt
• invoice.* – Rechnung finalisiert, bezahlt, teilbezahlt, überfällig, storniert
• payment.* – Zahlung erfolgreich, fehlgeschlagen, erstattet, Rücklastschrift
• dunning.* – Mahnstufe eskaliert, Mahnung pausiert/fortgesetzt
• test.ping – für Verbindungstests

Aufbau einer Zustellung

Jede Zustellung ist ein JSON-POST mit stabilem Umschlag: id (Ereignis-ID), type, created, account_id, data.object (das betroffene Objekt) und bei Änderungen previous_attributes. Mit dabei sind die Header X-Kyvento-Event (Typ), X-Kyvento-Delivery-Id (eindeutig je Zustellversuch) und die Signatur.

Signatur prüfen (dringend empfohlen)

Der Header X-Kyvento-Signature hat die Form t=<zeitstempel>,v1=<signatur>. Die Signatur ist ein HMAC-SHA256 über die Zeichenkette zeitstempel.request-body mit Ihrem Signing-Secret als Schlüssel. Prüfen Sie beides: Signatur korrekt und Zeitstempel nicht älter als 5 Minuten – so weisen Sie gefälschte und wiederholte Zustellungen ab.

Verbindung testen

Die Aktion „Test senden" schickt sofort ein Beispiel-Ereignis an Ihre URL – ideal, um Erreichbarkeit und Verarbeitung zu prüfen, bevor echte Ereignisse fließen. Beachten Sie: Die Test-Zustellung dient dem Verbindungstest und trägt keine Signatur – testen Sie die Signaturprüfung mit einem echten Ereignis (etwa test.ping über die API oder einer realen Änderung).

Nächste Schritte

• Zustellwiederholungen und Fehlerdiagnose – siehe „Webhook Retry und Fehlerbehandlung"
• Zusammenspiel mit der REST-API – siehe „API-Dokumentation und Beispiele"