Webhook-Endpunkt verifizieren

Überblick

Kyvento stellt Webhook-Ereignisse ausschließlich an verifizierte Endpunkte zu. Die Verifikation weist nach, dass die hinterlegte URL unter Ihrer Kontrolle steht. Sie erfolgt nach dem Challenge-Response-Verfahren: Kyvento sendet einen einmaligen Prüfwert an die Endpunkt-URL, und der Endpunkt gibt diesen Wert in derselben HTTP-Antwort zurück.

Dieser Artikel beschreibt den Ablauf, das Format der Verifikationsanfrage und die erwartete Antwort. Er richtet sich an die technische Ansprechperson, die den Endpunkt betreibt.

Ablauf

1. Endpunkt anlegen unter Einstellungen → „Webhooks". Das Signing-Secret wird einmalig angezeigt und ist sicher zu hinterlegen. Details: Webhooks konfigurieren.
2. Endpunkt vorbereiten. Der Endpunkt muss Verifikationsanfragen erkennen und den enthaltenen Prüfwert synchron zurückgeben (Format siehe unten).
3. Verifikation auslösen über die Schaltfläche „Endpunkt verifizieren". Kyvento sendet die Verifikationsanfrage sofort, wertet die Antwort im selben Vorgang aus und zeigt das Ergebnis in der Oberfläche an.

Die Verifikationsanfrage

Kyvento sendet einen einzelnen POST-Request an die Endpunkt-URL. Aufbau und Signatur entsprechen einer regulären Zustellung. Der Request-Body enthält den Typ endpoint.verification und das Feld challenge mit einem 64 Zeichen langen hexadezimalen Prüfwert:

POST /webhooks/kyvento HTTP/1.1
Host: ihre-anwendung.example
Content-Type: application/json; charset=utf-8
User-Agent: Kyvento-Webhooks/2.0
X-Kyvento-Event: endpoint.verification
X-Kyvento-Account-Id: 128
X-Kyvento-Delivery-Id: evt_del_verify_yQ3nR7pKmA1vTz8bXsLd
X-Kyvento-Signature: t=1755340800,v1=6f1c8b3a…

{
  "type": "endpoint.verification",
  "challenge": "3f9a1c47b28e5d60a4f7c1938be25d0af6172c8d94e30b5a7fd82169c4e0ab73"
}

Der Prüfwert wird für jede Verifikation neu erzeugt und von Kyvento nicht gespeichert. Der Endpunkt muss den Wert aus der jeweils aktuellen Anfrage zurückgeben; ein zwischengespeicherter Wert aus einer früheren Anfrage wird nicht akzeptiert.

Für den Endpunkt hinterlegte Basic-Authentifizierung und eigene HTTP-Header werden auch bei der Verifikationsanfrage übermittelt.

Die erwartete Antwort

Der Endpunkt muss innerhalb desselben Requests mit HTTP-Status 200 antworten und den Prüfwert unverändert zurückgeben. Zwei Antwortformate werden akzeptiert:

Format 1: Prüfwert als Response-Body

HTTP/1.1 200 OK
Content-Type: text/plain

3f9a1c47b28e5d60a4f7c1938be25d0af6172c8d94e30b5a7fd82169c4e0ab73

Format 2: JSON-Objekt mit dem Feld challenge

HTTP/1.1 200 OK
Content-Type: application/json

{"challenge":"3f9a1c47b28e5d60a4f7c1938be25d0af6172c8d94e30b5a7fd82169c4e0ab73"}

Führende und abschließende Leerzeichen oder Zeilenumbrüche im Body werden ignoriert. Zusätzliche Felder im JSON-Objekt sind zulässig, sofern das Feld challenge enthalten ist.

Beispielimplementierung

Die Verifikationsanfrage wird vor der regulären Ereignisverarbeitung behandelt. Das folgende Beispiel in PHP lässt sich auf jede Sprache übertragen:

$payload = json_decode(file_get_contents('php://input'), true);

// Verifikationsanfrage: Prüfwert unverändert zurückgeben.
if (($payload['type'] ?? null) === 'endpoint.verification') {
    header('Content-Type: text/plain');
    http_response_code(200);
    echo $payload['challenge'];
    exit;
}

// Reguläre Ereignisverarbeitung.

Verarbeitet Ihre Anwendung eingehende Ereignisse asynchron, beispielsweise über eine Warteschlange, muss die Verifikationsanfrage davon ausgenommen werden. Der Prüfwert wird in der Antwort auf denselben Request erwartet.

Anforderungen an den Endpunkt

• Öffentliche Erreichbarkeit: Adressen in privaten oder reservierten Netzbereichen werden abgelehnt.
• Gültiges TLS-Zertifikat: Die Verbindung wird über HTTPS aufgebaut. Ein abgelaufenes oder unvollständiges Zertifikat führt zum Abbruch.
• Keine Weiterleitungen: HTTP-Redirects (301, 302) werden nicht gefolgt. Hinterlegen Sie die endgültige Adresse.
• Antwortzeit: Die Antwort muss innerhalb von 10 Sekunden eintreffen. Der Vorgang läuft synchron.
• Signaturprüfung: Die Verifikationsanfrage trägt eine gültige Signatur im Header X-Kyvento-Signature. Eine Prüfung ist möglich, aber für die Verifikation nicht erforderlich. Das Prüfverfahren beschreibt Webhooks konfigurieren.

Gültigkeit der Verifikation

• Änderung der Endpunkt-URL: Die Verifikation ist an die geprüfte Adresse gebunden. Nach einer Änderung der URL ist der Endpunkt erneut zu verifizieren; bis dahin erfolgen keine Zustellungen.
• Fehlgeschlagene erneute Verifikation: Ein fehlgeschlagener Verifikationsversuch hebt eine bestehende Verifikation nicht auf. Bei vorübergehender Nichterreichbarkeit greifen die regulären Zustellwiederholungen – siehe Webhook Retry und Fehlerbehandlung.
• Begrenzung: Verifikationsanfragen sind auf zehn pro Minute und Benutzer begrenzt.

Fehlermeldungen

Prüfung nach erfolgreicher Verifikation

1. Das Abzeichen des Endpunkts wechselt auf „Verifiziert"; der Hinweis auf die ausstehende Verifikation wird nicht mehr angezeigt.
2. Lösen Sie eine Testzustellung aus und prüfen Sie, ob Ihre Anwendung das Beispiel-Ereignis verarbeitet.
3. Prüfen Sie die Verarbeitung eines regulären Ereignisses, beispielsweise durch das Anlegen einer Testrechnung.

Weiterführende Artikel

• Endpunkt anlegen, Ereignisse auswählen und Signatur prüfen – Webhooks konfigurieren
• Zustellwiederholungen und Fehlerdiagnose – Webhook Retry und Fehlerbehandlung
• Zusammenspiel mit der REST-API – API-Dokumentation und Beispiele