Dokumentation · Integrationshandbuch

Webhook-Integration

Dieses Dokument erklärt, wie die ausgehenden Webhooks des ADP Car Market Hub-Plugins funktionieren, wie Sie diese sicher konfigurieren, wie ein empfangendes System die Payloads validieren sollte und was im Betrieb zu erwarten ist. Es deckt auch die Einschränkungen der aktuellen Implementierung ab, damit Integrationen entsprechend konzipiert werden können.

Wann Sie dieses Dokument verwenden sollten

Verwenden Sie dieses Dokument, wenn Sie:

das Plugin mit einem CRM, einem Lead-Routing-Tool, einem Benachrichtigungsdienst oder einer Plattform zur Workflow-Automatisierung verbinden.
den empfangenden Endpunkt erstellen oder betreiben, den das Plugin aufrufen soll.
das Sicherheitskonzept einer Webhook-Integration überprüfen.
Fehler bei einem Empfänger beheben, der scheinbar nicht aufgerufen wird oder der Payloads ablehnt.

Die Zielgruppe ist ein Integrator oder Entwickler, der am empfangenden System arbeitet, zusammen mit dem WordPress-Administrator, der das Plugin konfiguriert.

Übersicht

Ein Webhook ist eine ausgehende HTTP-Anfrage, die das Plugin an eine URL Ihrer Wahl sendet, wenn ein bestimmtes Ereignis auf der WordPress-Website eintritt. Das Plugin sendet ein JSON-Dokument, das das Ereignis beschreibt; das empfangende System verarbeitet dieses nach Belieben (Erstellen eines CRM-Tickets, Senden einer Chat-Nachricht, Anhängen an eine Tabellenkalkulation, Weiterleiten eines Leads usw.).

Das Plugin stellt derzeit zwei Ereignisse bereit:

new_lead — wird ausgelöst, wenn ein Besucher das Kontaktformular auf einer Fahrzeugseite absendet und ein Lead gespeichert wird.
new_import — wird ausgelöst, wenn ein Fahrzeug durch den Importer importiert oder aktualisiert wird.

Hinweis zum aktuellen Verhalten: In der aktuellen Plugin-Version wird nur new_import tatsächlich gesendet. Der Pfad für new_lead ist zwar vorbereitet (Ziel-URL, Secret und Signierung funktionieren), aber der Auslöser ist im aktuellen Code nicht aktiv, sodass eine konfigurierte new_lead-URL noch keine Anfragen empfängt. Nutzen Sie in der Zwischenzeit die integrierten Lead-E-Mails für Lead-Benachrichtigungen und konfigurieren Sie new_lead jetzt, wenn Sie den Empfänger für den Zeitpunkt der Aktivierung vorbereiten möchten.

Jedes Ereignis hat seine eigene konfigurierbare Ziel-URL. Es kann ein einzelnes gemeinsames Secret konfiguriert werden, um jede Payload mit HMAC-SHA256 zu signieren, sodass der Empfänger überprüfen kann, ob die Anfrage wirklich vom Plugin stammt.

Webhooks sind optional. Wenn keine Ziel-URL konfiguriert ist, wird für dieses Ereignis keine Anfrage gesendet.

Voraussetzungen

Bereiten Sie vor der Konfiguration von Webhooks Folgendes vor:

Einen empfangenden Endpunkt, der eine HTTPS-POST-Anfrage mit einem JSON-Body akzeptiert. HTTPS wird dringend empfohlen; ein HTTP-Endpunkt legt die Payload während der Übertragung offen.
Kenntnisse darüber, wie der Empfänger auf Fehler reagiert, damit das unten beschriebene Wiederholungsverhalten für Ihr Setup Sinn ergibt.
Einen gemeinsamen Secret-Wert, den Sie sowohl im Plugin als auch im Empfänger konfigurieren können (nur erforderlich, wenn Sie eine Signaturprüfung wünschen — dringend empfohlen).
WordPress-Administratorzugriff auf der Website, auf der das Plugin läuft.

Schritt-für-Schritt-Anleitung

Entscheiden Sie, welche Ereignisse weitergeleitet werden sollen. Sie können entweder new_lead, new_import oder beide konfigurieren. Lassen Sie eine Ziel-URL leer, um dieses Ereignis zu deaktivieren.
Wählen Sie ein gemeinsames Secret. Verwenden Sie eine lange, zufällige Zeichenfolge (z. B. ein generiertes Passwort aus Ihrem Passwort-Manager). Halten Sie es geheim — es darf niemals veröffentlicht werden.
Öffnen Sie die Plugin-Einstellungen. Navigieren Sie zu Car Market Hub → Leads. Der Bereich „Webhooks“ auf dem Reiter „Leads“ enthält die Felder New lead webhook URL, New import webhook URL und Webhook secret. Überprüfen Sie die genaue Platzierung in der aktuellen Plugin-Version, da sich die UI-Gruppierung zwischen den Versionen ändern kann.
Konfigurieren Sie die URLs. Fügen Sie die Empfänger-URLs in die entsprechenden Felder ein. Das Plugin prüft, ob der Wert eine syntaktisch korrekte URL ist, und überspringt die Zustellung, wenn sie fehlt oder ungültig ist.
Konfigurieren Sie das Secret. Fügen Sie das gemeinsame Secret in das Feld Webhook secret ein. Konfigurieren Sie denselben Wert im Empfänger.
Speichern und einen Test auslösen. Speichern Sie die Einstellungen und lösen Sie dann ein echtes Ereignis aus: - Für new_lead: Senden Sie das Lead-Formular auf einer Fahrzeug-Detailseite aus einem privaten Fenster ab. - Für new_import: Führen Sie den Importer aus (manuell oder warten Sie auf den nächsten geplanten Durchlauf), sodass mindestens ein Fahrzeug hinzugefügt oder aktualisiert wird.
Empfang bestätigen. Überprüfen Sie die Protokolle des Empfängers, um zu bestätigen, dass die Anfrage angekommen ist und die Signatur erfolgreich verifiziert wurde. Wenn etwas nicht stimmt, lesen Sie den Abschnitt Fehlerbehebung weiter unten.

Konfigurations-Referenz

Einstellung	Zweck
New lead webhook URL	Endpunkt, der aufgerufen wird, wenn eine Kontaktformular-Einsendung als Lead gespeichert wird.
New import webhook URL	Endpunkt, der aufgerufen wird, wenn ein Fahrzeug durch den Importer importiert oder aktualisiert wird.
Webhook secret	Gemeinsames Secret, das verwendet wird, um jede Payload mit HMAC-SHA256 zu signieren. Wenn es leer ist, wird kein Signatur-Header gesendet.

Die entsprechenden Optionsschlüssel, die intern vom Plugin verwendet werden, sind in Option Keys and Settings Storage und der Webhook-Ereignisreferenz dokumentiert.

Anfrageformat

Das Plugin sendet jedes Ereignis als HTTPS-POST-Anfrage mit einem JSON-Body und den folgenden Headern:

Content-Type: application/json
X-AS24CI-Signature: <hex> — nur vorhanden, wenn ein Webhook-Secret konfiguriert ist. Der Wert ist der HMAC-SHA256 des rohen Anfrage-Bodys, wobei das konfigurierte Secret als Schlüssel verwendet und als kleingeschriebener Hexadezimal-String codiert wird.

Die genaue Feldstruktur im JSON-Body kann sich zwischen den Plugin-Versionen weiterentwickeln. Die Referenz für die aktuelle Version finden Sie in der Webhook-Ereignisreferenz. Beide Ereignisse enthalten mindestens:

event — den Ereignisnamen (new_lead oder new_import).
timestamp — einen ISO-8601-Zeitstempel in UTC, wann das Ereignis vorbereitet wurde.
Eine Kennung für das zugehörige WordPress-Objekt (Lead-ID für new_lead, Post-ID und Listing-ID für new_import).
Ein data-Objekt mit einem kleinen Satz von Zusammenfassungsfeldern zum Ereignis (Basis-Lead-Felder für new_lead; Basis-Fahrzeugfelder für new_import).

Empfänger sollten unbekannte Felder als abwärtskompatible Ergänzungen behandeln und sie ignorieren, anstatt die Payload abzulehnen. Überprüfen Sie die aktuelle Feldstruktur vor der Veröffentlichung Ihrer Integration anhand des Referenzdokuments.

Eingehende Anfragen validieren

Wenn ein Webhook-Secret konfiguriert ist, sollte der Empfänger immer die Signatur überprüfen, bevor er der Payload vertraut. Die Validierungsregel lautet:

Lesen Sie den rohen Anfrage-Body vor jeglichem JSON-Parsing (Parsing und anschließende Re-Serialisierung können die Byte-Reihenfolge oder Leerzeichen ändern und die Signatur ungültig machen).
Berechnen Sie HMAC-SHA256(raw_body, shared_secret) und codieren Sie das Ergebnis als kleingeschriebenen Hexadezimal-String.
Vergleichen Sie diesen mit dem Wert des Headers X-AS24CI-Signature unter Verwendung eines zeitkonstanten Vergleichs (die meisten Sprachen bieten dies als hash_equals, crypto.timingSafeEqual, hmac.compare_digest oder ähnlich an).
Weisen Sie die Anfrage mit 401 ab, wenn die Signatur fehlt oder nicht übereinstimmt.

Zusätzliche Schutzmaßnahmen, die der Empfänger in Betracht ziehen sollte:

HTTP ablehnen. Akzeptieren Sie am Empfänger nur HTTPS-Anfragen.
Die Quell-IP zulassen. Setzen Sie die IP-Adresse der WordPress-Website zusätzlich zur Signaturprüfung auf eine Whitelist auf Netzwerk- oder Anwendungsebene.
Idempotenz. Dasselbe logische Ereignis kann mehr als einmal zugestellt werden (siehe Zustellungsverhalten unten). Verwenden Sie die Lead-ID, die Post-ID, die Listing-ID oder einen Hash der Payload zur Deduplizierung auf Empfängerseite.
Zeitstempel-Fenster. Weisen Sie Anfragen ab, deren timestamp weit in der Vergangenheit oder Zukunft liegt, um die Nutzbarkeit abgefangener Payloads einzuschränken. Eine geringfügige Uhrzeitabweichung von einigen Minuten auf beiden Seiten ist normal.
Schema-Toleranz. Behandeln Sie zusätzliche Felder als abwärtskompatibel und unbekannte Ereignisnamen als etwas, das protokolliert, aber nicht zum Absturz führen sollte.
Begrenzung der Body-Größe. Begrenzen Sie die maximale Body-Größe am Empfänger, um sich vor fehlerhaften Eingaben zu schützen.

Wenn kein Secret konfiguriert ist, hat der Empfänger keine Möglichkeit zu überprüfen, ob die Anfrage wirklich vom Plugin stammt. Konfigurieren Sie ein Secret, es sei denn, der Netzwerkpfad ist vollständig privat und vertrauenswürdig.

Zustellungsverhalten

Die aktuelle Implementierung weist die folgenden Zustellungsmerkmale auf. Überprüfen Sie diese Verhaltensweisen in der aktuellen Plugin-Version, bevor Sie sich darauf verlassen.

Der erste Versuch erfolgt nach dem Prinzip „Fire-and-Forget“. Wenn ein Ereignis ausgelöst wird, sendet das Plugin die erste Zustellung als nicht-blockierenden HTTP-POST. Es wartet nicht auf die Antwort des Empfängers und wertet den Antwortcode bei diesem Versuch nicht aus.
Geplante Wiederholungsversuche. Kurze Zeit nach dem ersten Versuch wird eine Folgezustellung über die Aufgabenwarteschlange von WordPress geplant. Wenn diese Zustellung eine 5xx-Antwort oder einen Verbindungsfehler zurückgibt, plant das Plugin weitere Wiederholungen mit einer kurzen, sich steigernden Verzögerung dazwischen.
Begrenzung der Wiederholungen. Das Plugin versucht die Zustellung nicht unendlich oft. Nach einer geringen Anzahl erfolgloser Versuche wird das Ereignis stillschweigend verworfen und nicht später zugestellt.
Unabhängigkeit pro Ereignis. Ein Zustellungsfehler bei einem Ereignis hat keinen Einfluss auf das nächste Ereignis.
Reihenfolge ist nicht garantiert. Zwei kurz nacheinander ausgelöste Ereignisse können in beliebiger Reihenfolge ankommen. Empfänger sollten sich auf IDs und Zeitstempel in der Payload verlassen, nicht auf die Reihenfolge des Eintreffens.
Einzel-Empfänger-Modell. Jedes Ereignis hat genau eine konfigurierte URL. Um Daten an mehrere Systeme zu verteilen, konfigurieren Sie einen kleinen Weiterleiter (z. B. eine Automatisierungsplattform wie Zapier, Make, n8n oder ein selbst gehostetes Relay) als Empfänger und lassen Sie diesen die Verteilung an die nachgelagerten Systeme übernehmen.
Cron-Abhängigkeit für Wiederholungen. Wiederholungen werden über die Aufgabenwarteschlange von WordPress geplant. Stellen Sie bei Installationen, die den Server-Cron-Modus verwenden (siehe Server Cron Setup), sicher, dass der begleitende Job, der wp-cron.php aufruft, eingerichtet ist — andernfalls werden geplante Wiederholungen nicht ausgeführt.

Betriebshinweise

Protokollierung auf der WordPress-Seite. Das Plugin protokolliert API- und Importaktivitäten in wp-content/uploads/as24ci-logs/. Die Webhook-Zustellung ist Teil des normalen Betriebs und erzeugt standardmäßig möglicherweise keine ausführlichen Protokolle. Der zuverlässigste Ort, um zu sehen, was zugestellt wurde, ist das eigene Protokoll des Empfängers.
Protokollierung auf der Empfängerseite. Protokollieren Sie jede empfangene Anfrage, einschließlich der Header (mit der Signatur) und des rohen Bodys, vor jeglicher Verarbeitung. Dies erleichtert sowohl die Reaktion auf Vorfälle als auch das Debugging erheblich. Wenden Sie die normalen Datenschutzregeln des Empfängers an — Leads enthalten personenbezogene Daten.
Personenbezogene Daten. Das new_lead-Ereignis enthält personenbezogene Daten, die vom Besucher übermittelt wurden (wie Name, E-Mail-Adresse, Telefonnummer, Nachricht). Behandeln Sie den Empfänger als Auftragsverarbeiter für diese Informationen und wenden Sie Ihre normalen Datenschutzregeln an. Siehe Lead Data and Consent und GDPR / DSGVO Notes.
Rotieren des Secrets. Wenn Sie das Webhook-Secret im Plugin ändern, aktualisieren Sie gleichzeitig den Empfänger. Bis beide Seiten übereinstimmen, wird jede Zustellung durch die Signaturprüfung abgelehnt.
Ändern der URL. Die Aktualisierung der URL wird für das nächste Ereignis wirksam. Es gibt keinen integrierten Mechanismus, um historische Ereignisse erneut zuzustellen.
Deaktivieren eines Webhooks. Löschen Sie das URL-Feld und speichern Sie. Es werden keine weiteren Ereignisse dieses Typs gesendet.

Einschränkungen

Es werden nur die beiden oben beschriebenen Ereignisse ausgegeben. Es gibt kein integriertes Ereignis für das Löschen von Fahrzeugen, Änderungen des Lead-Status, Suchauftrags-Abonnements, Probefahrt-Buchungen oder andere Plugin-Aktionen.
Es gibt keine Admin-Benutzeroberfläche zur Überprüfung einzelner Zustellungsversuche oder zum erneuten Abspielen historischer Ereignisse.
Es gibt keine native Verteilung (Fan-out) an mehrere Empfänger pro Ereignis.
Es gibt keinen Endpunkt für eingehende Webhooks — das Plugin sendet nur Webhooks; es akzeptiert keine beliebigen eingehenden Webhooks.
Die Anzahl der Wiederholungsversuche und Verzögerungen kann sich zwischen den Plugin-Versionen ändern. Überprüfen Sie das aktuelle Verhalten anhand der Webhook-Ereignisreferenz, bevor Sie Kundendokumentationen veröffentlichen.

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Was zu prüfen ist
Empfänger sieht niemals eine Anfrage.	Die Webhook-URL ist leer, fehlerhaft oder von der WordPress-Website aus nicht erreichbar (DNS, Firewall, ausgehendes HTTPS blockiert).	Überprüfen Sie die URL auf dem Reiter „Leads“ erneut. Bestätigen Sie, dass ausgehendes HTTPS vom WordPress-Host aus funktioniert (siehe API-, Netzwerk- und SSL-Anforderungen).
Empfänger sieht die Anfrage, aber die Signatur stimmt nicht überein.	Der Empfänger verifiziert den analysierten Body anstelle der Rohbytes, das Secret unterscheidet sich auf beiden Seiten oder der Vergleich erfolgt nicht in konstanter Zeit.	Stellen Sie sicher, dass der Roh-Body vor dem JSON-Parsing gelesen wird, dass das Secret exakt übereinstimmt (keine Leerzeichen, keine Zeilenumbrüche) und dass der Vergleich eine Constant-Time-Funktion verwendet.
Empfänger sieht die Anfrage, aber `X-AS24CI-Signature` fehlt.	Das Webhook-Secret ist in den Plugin-Einstellungen leer.	Legen Sie ein Secret fest, speichern Sie und testen Sie erneut.
Übermittlungen des Lead-Formulars kommen beim Empfänger an, aber derselbe Lead wird mehrmals zugestellt.	Erwartet: Das Plugin versucht erneute Zustellungen, wenn ein vorheriger Zustellversuch als erfolglos eingestuft wurde, und der erste Versuch erfolgt nach dem Prinzip „Fire-and-Forget“.	Machen Sie den Empfänger idempotent, indem Sie `lead_id` (oder einen anderen stabilen Identifikator aus dem Payload) verwenden.
`new_import`-Ereignisse kommen nicht an, obwohl Importe laufen.	Die Webhook-URL für neue Importe ist leer oder falsch konfiguriert.	Überprüfen Sie die URL auf dem Reiter „Leads“ erneut; verifizieren Sie dies mit einem manuellen Import.
Erneute Zustellversuche scheinen nicht stattzufinden.	WP-Cron ist deaktiviert und es ist kein begleitender `wp-cron.php`-Cron-Job eingerichtet.	Siehe Server Cron Setup und fügen Sie den begleitenden Job hinzu.
Empfänger gibt bei Vorfällen wiederholt `5xx` zurück.	Normaler Fehlermodus. Das Plugin versucht es einige Male erneut und gibt dieses Ereignis dann auf.	Machen Sie den Empfänger tolerant oder puffern Sie auf Empfängerseite. Es gibt keine integrierte Admin-Wiederholung.
Der Webhook-Secret-Wert erscheint in einem Protokoll oder Screenshot.	Unzureichende Schwärzung.	Rotieren Sie das Secret unverzüglich, aktualisieren Sie das Plugin sowie den Empfänger und testen Sie erneut.