Webhooks

Dieses Dokument beschreibt die ausgehenden HTTP-Webhooks, die vom ADP Car Market Hub-Plugin ausgelöst werden, damit externe CRM-, Benachrichtigungs- oder Automatisierungssysteme in Echtzeit auf Plugin-Ereignisse reagieren können.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

• Das Plugin mit einem externen CRM- oder Benachrichtigungsdienst verbinden (z. B. einem Workflow-Automatisierungstool), damit neue Leads oder neu importierte Fahrzeuge Aktionen in einem anderen System auslösen.
• Einen Empfänger-Endpunkt implementieren, der die Authentizität des Webhooks mithilfe der HMAC-Signatur überprüft.
• Ausgebliebene oder doppelte Webhook-Zustellungen diagnostizieren.

Für eingehendes HTTP siehe REST-API-Endpunkte.

Übersicht

Das Plugin kann zwei ausgehende Webhook-Ereignisse auslösen:

• new_lead — soll ausgelöst werden, wenn eine Kontaktformular-Übermittlung als Lead-Beitrag gespeichert wird. AS24CI\Webhooks lauscht auf die Aktion as24ci_lead_saved, aber in der aktuellen Plugin-Version wird diese Aktion nirgendwo im Code ausgelöst (der Lead wird über Leads_CPT::save_lead() gespeichert, ohne den Hook auszulösen), sodass der Webhook new_lead derzeit nicht ausgelöst wird. Behandeln Sie dieses Ereignis als inaktiv, bis der Auslösepunkt wiederhergestellt ist.
• new_import — wird ausgelöst, wenn ein Fahrzeug während eines Imports erstellt oder aktualisiert wird (über die Aktion as24ci_vehicle_imported). Dieses Ereignis ist aktiv.

Jedes Ereignis sendet einen JSON-Payload per POST an eine vom Administrator konfigurierte URL. Wenn ein gemeinsames Geheimnis (Shared Secret) konfiguriert ist, trägt jede Anfrage zudem einen HMAC-SHA256-Signatur-Header, den der Empfänger zur Verifizierung des Payloads verwenden kann.

Webhooks sind unabhängig voneinander: Die Konfiguration des einen aktiviert nicht den anderen. Wenn Sie eine URL leer lassen, wird dieses Ereignis vollständig deaktiviert.

Anforderungen oder Voraussetzungen

• Ein erreichbarer HTTPS-Endpunkt auf der Empfängerseite.
• (Optional, aber dringend empfohlen) ein im Plugin und auf dem Empfänger hinterlegtes gemeinsames Geheimnis (Shared Secret), das zur Überprüfung der Signatur verwendet wird.
• Für das Ereignis new_lead: Beachten Sie den obigen Vorbehalt — die Aktion as24ci_lead_saved wird derzeit nicht ausgelöst, sodass dieses Ereignis in der aktuellen Plugin-Version auch bei konfigurierter URL nicht ausgelöst wird.
• Für das Ereignis new_import: Die Import-Engine muss konfiguriert sein und laufen. Siehe Import-Engine.

Schritt-für-Schritt-Anleitung

1. Öffnen Sie den Plugin-Adminbereich und suchen Sie die Webhook-Felder. Diese befinden sich auf dem Tab Leads als Eingabefelder mit den Bezeichnungen New lead webhook URL, New import webhook URL und Webhook secret.
2. Geben Sie eine gültige https://-URL für jedes Ereignis ein, das Sie empfangen möchten.
3. Generieren Sie ein starkes, zufälliges Geheimnis (z. B. eine Zeichenfolge mit mehr als 32 Zeichen) und fügen Sie es in das Feld Webhook secret ein. Konfigurieren Sie denselben Wert auf dem Empfänger.
4. Speichern Sie die Einstellungen. Das Plugin speichert die Werte in den Optionen as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import und as24ci_webhook_secret.
5. Lösen Sie ein Testereignis aus: - Für new_lead: Senden Sie ein Test-Kontaktformular im Frontend ab. - Für new_import: Führen Sie einen Import aus, der mindestens ein Fahrzeug erstellt oder aktualisiert.
6. Bestätigen Sie den Empfang und die Signaturprüfung auf der Empfängerseite.

Payload-Referenz

Alle Payloads sind JSON-Objekte mit event, timestamp (ISO 8601, UTC) und einem für event spezifischen Datenblock.

new_lead

{
  "event": "new_lead",
  "timestamp": "2025-01-01T12:00:00+00:00",
  "lead_id": 123,
  "data": {
    "name": "",
    "email": "",
    "phone": "",
    "message": "",
    "vehicle_id": 0,
    "vehicle_title": "",
    "vehicle_url": ""
  }
}

new_import

{
  "event": "new_import",
  "timestamp": "2025-01-01T12:00:00+00:00",
  "post_id": 456,
  "listing_id": "",
  "data": {
    "title": "",
    "url": "",
    "make": "",
    "model": "",
    "price": 0
  }
}

Der Payload für new_import wird sowohl bei neuen Einfügungen als auch bei Aktualisierungen ausgelöst. Der Hook-Callback erhält intern ein Flag is_update; der ausgehende Payload selbst enthält dieses Flag in der aktuellen Plugin-Version nicht. Prüfen Sie, ob Ihre Integration eine Unterscheidung der beiden Fälle erfordert, und gleichen Sie das aktuelle Verhalten mit dem Quellcode ab, bevor Sie kundenorientierte Formulierungen veröffentlichen.

Authentifizierung und Signaturprüfung

Wenn die Option as24ci_webhook_secret gesetzt ist, fügt das Plugin folgenden Header hinzu:

X-AS24CI-Signature: <hmac_sha256(payload_json, secret)>

Die Signatur wird über den exakten JSON-Body berechnet, der in der Anfrage gesendet wird. Zur Überprüfung auf dem Empfänger:

1. Lesen Sie den rohen Anfrage-Body aus, ohne ihn neu zu kodieren.
2. Berechnen Sie hash_hmac('sha256', body, secret) unter Verwendung desselben gemeinsamen Geheimnisses.
3. Vergleichen Sie das Ergebnis mit X-AS24CI-Signature mittels eines zeitkonstanten Vergleichs (z. B. hash_equals in PHP).

Wenn kein Geheimnis konfiguriert ist, wird der Header X-AS24CI-Signature nicht gesendet. In Produktionsumgebungen sollte immer ein Geheimnis konfiguriert werden.

Zustellung, Wiederholungsversuche und Timeouts

• Anfragen verwenden wp_remote_post() mit einem Timeout von 15 Sekunden.
• Der erste Versuch ist nicht-blockierend (fire and forget). Das Plugin plant dann ein nachfolgendes Cron-Ereignis (as24ci_webhook_retry) etwa 60 Sekunden später, das einen blockierenden Neuversand durchführt, damit der Antwortcode überprüft werden kann.
• Wenn die Antwort ein Verbindungsfehler oder HTTP 5xx ist, plant das Plugin zusätzliche Wiederholungsversuche mit exponentiellem Backoff (~2 Minuten, dann ~4 Minuten), bis zu maximal drei Versuchen insgesamt.
• HTTP 4xx-Antworten werden als endgültig behandelt und nicht wiederholt; beheben Sie den Fehler auf Empfängerseite und lösen Sie das Quellereignis bei Bedarf erneut aus.
• Empfänger sollten innerhalb von 15 Sekunden antworten und rechenintensive Arbeiten idealerweise asynchron ausführen.

Konfigurationsreferenz

Die vollständige Liste der Plugin-Optionen finden Sie unter Speicherung von Optionen und Einstellungen.

Betriebshinweise

• URLs werden mit filter_var( ..., FILTER_VALIDATE_URL ) validiert. Ungültige URLs werden stillschweigend übersprungen — richten Sie in der Produktionsumgebung gültige https://-URLs ein.
• Das Plugin löst Webhooks nur aus; es verwaltet keine Zustellungswarteschlange, kein Protokoll für Wiederholungen und keinen Dead-Letter-Speicher. Wenn eine zuverlässige, geordnete Zustellung für Ihren Anwendungsfall kritisch ist, leiten Sie den Empfänger über eine Warteschlangenschicht (z. B. eine Serverless-Funktion mit integrierter Wiederholungswarteschlange).
• Jeder Webhook wird aus derselben WordPress-Anfrage ausgelöst, die das Quellereignis generiert hat. Langsame Empfänger blockieren die benutzerseitige Anfrage nicht, da der erste Versuch nicht-blockierend ist.
• Der Payload new_lead enthält nur den oben gezeigten kleinen Satz an Feldern. Zusätzliche Lead-Metadaten sind über die WP-REST-API oder durch Abfrage des Beitragstyps as24ci_lead mit normalen WordPress-Funktionen verfügbar.
• Der Payload new_import wird bewusst klein gehalten. Um den vollständigen Fahrzeugdatensatz abzurufen, rufen Sie /wp-json/as24ci/v1/vehicles/<post_id> auf (wenn die öffentliche REST-API aktiviert ist).

Fehlerbehebung

• Webhook kommt nie an — Überprüfen Sie, ob die URL HTTPS verwendet, vom WordPress-Server aus erreichbar ist und als URL validiert wird. Überprüfen Sie die Plugin-Protokolle und das Fehlerprotokoll Ihres Webservers.
• Webhook kommt einmal an, aber keine Wiederholungen — Der erste Versuch ist absichtlich nach dem Prinzip „Fire-and-Forget“; überprüfen Sie, ob das Ereignis as24ci_webhook_retry geplant wird (es basiert auf WP-Cron oder Ihrem externen Cron).
• Signaturfehler auf Empfängerseite — Bestätigen Sie, dass beide Seiten exakt dasselbe Geheimnis verwenden und dass der Empfänger den rohen Anfrage-Body überprüft, ohne ihn vor dem Hashing neu zu serialisieren oder zu formatieren.
• Doppelte new_import-Zustellungen — Die Änderungserkennung überspringt Fahrzeuge, deren Payload unverändert ist, aber eine erzwungene vollständige Synchronisierung kann Ereignisse für bereits bekannte Inserate erneut auslösen. Siehe Import-Engine für die Regeln zur Änderungserkennung.
• Hängende Wiederholungen — WP-Cron erfordert regelmäßigen Website-Traffic, um ausgelöst zu werden. Richten Sie auf Websites mit geringem Traffic einen echten Cronjob oder den in Cron-Ereignisse und Scheduler beschriebenen REST-Cron-Endpunkt ein.

Verwandte Dokumente

• REST-API-Endpunkte
• Cron-Ereignisse und Scheduler
• Speicherung und Verarbeitung von Leads
• Import-Engine
• Speicherung von Optionen und Einstellungen
• Sicherheit und Berechtigungen