Webhooks konfigurieren

Ü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.

Endpunkt verifizieren

Bevor Ereignisse fließen, muss nachgewiesen sein, dass die eingetragene Adresse Ihnen gehört: Kyvento sendet einmalig einen Prüfwert an die URL, den Ihr Server mit Status 200 unverändert zurückgeben muss. Solange dieser Nachweis fehlt, trägt der Endpunkt das Abzeichen „Nicht verifiziert" und erhält keine Zustellungen – auch dann nicht, wenn er aktiv ist. Nach jeder Änderung der Endpunkt-URL ist der Nachweis erneut zu erbringen. Den vollständigen Ablauf mit Beispiel-Zustellung und Beispiel-Antwort beschreibt Webhook-Endpunkt verifizieren.

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. Die Test-Zustellung läuft über denselben Weg wie eine echte und trägt daher dieselbe Signatur – Sie können Ihre Signaturprüfung also direkt damit testen. Erkennbar ist sie am zusätzlichen Header X-Kyvento-Test: 1 und am Feld test im Rumpf; in der Zustellhistorie erscheint sie nicht.

Nächste Schritte

• Nachweis über die Endpunkt-Adresse erbringen – siehe Webhook-Endpunkt verifizieren
• Zustellwiederholungen und Fehlerdiagnose – siehe Webhook Retry und Fehlerbehandlung
• Zusammenspiel mit der REST-API – siehe API-Dokumentation und Beispiele