Dokumentation · Technische Dokumentation

Webhooks

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

Wann dieses Dokument zu verwenden ist

Lesen Sie dieses Dokument, wenn Sie:

  • Das Plugin mit einem externen CRM oder Benachrichtigungsdienst verbinden müssen (z. B. einem Workflow-Automations-Tool), 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.
  • Fehlende oder doppelte Webhook-Zustellungen diagnostizieren müssen.

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 ein Kontaktformular-Formulareintrag als Lead-Post gespeichert wird. AS24CI\Webhooks lauscht auf die as24ci_lead_saved-Aktion, aber in der aktuellen Plugin-Version wird diese Aktion nirgends im Code ausgelöst (der Lead wird über Leads_CPT::save_lead() gespeichert, ohne den Hook auszulösen), weshalb der new_lead-Webhook 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 as24ci_vehicle_imported-Aktion). Dieses Ereignis ist aktiv.

Jedes Ereignis sendet einen JSON-Payload per POST an eine vom Administrator konfigurierte URL. Wenn ein 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: Die Konfiguration des einen aktiviert nicht den anderen. Wenn eine URL leer gelassen wird, wird dieses Ereignis vollständig deaktiviert.

Anforderungen oder Voraussetzungen

  • Ein erreichbarer HTTPS-Endpunkt auf der Empfängerseite.
  • (Optional, aber dringend empfohlen) ein in den Plugin-Einstellungen und beim Empfänger hinterlegtes Shared Secret, das zur Überprüfung der Signatur verwendet wird.
  • Für das new_lead-Ereignis: Beachten Sie den obigen Vorbehalt — die as24ci_lead_saved-Aktion wird derzeit nicht ausgelöst, sodass dieses Ereignis in der aktuellen Plugin-Version auch mit konfigurierter URL nicht ausgelöst wird.
  • Für das new_import-Ereignis: 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 Secret (z. B. eine Zeichenkette mit mindestens 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 Testerreignis 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 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 new_import-Payload wird sowohl bei neuen Einfügungen als auch bei Aktualisierungen ausgelöst. Der Hook-Callback erhält intern ein is_update-Flag; der ausgehende Payload selbst enthält dieses Flag in der aktuellen Plugin-Version nicht. Prüfen Sie, ob Ihre Integration die Unterscheidung dieser beiden Fälle erfordert, und gleichen Sie das aktuelle Verhalten mit dem Quellcode ab, bevor Sie kundenorientierte Texte 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 ein, ohne ihn neu zu kodieren.
  2. Berechnen Sie hash_hmac('sha256', body, secret) mit demselben Shared Secret.
  3. Vergleichen Sie das Ergebnis mit X-AS24CI-Signature unter Verwendung eines zeitkonstanten Vergleichs (z. B. hash_equals in PHP).

Wenn kein Secret konfiguriert ist, wird der Header X-AS24CI-Signature nicht gesendet. In Produktivumgebungen sollte immer ein Secret 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 Neuversuch durchführt, damit der Antwortcode überprüft werden kann.
  • Wenn die Antwort ein Verbindungsfehler oder HTTP 5xx ist, plant das Plugin weitere 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.

Konfigurations-Referenz

OptionsschlüsselGespeicherter Wert
as24ci_webhook_url_new_leadURL, die für das Ereignis new_lead aufgerufen wird. Leer deaktiviert das Ereignis.
as24ci_webhook_url_new_importURL, die für das Ereignis new_import aufgerufen wird. Leer deaktiviert das Ereignis.
as24ci_webhook_secretShared Secret zur Signierung von Payloads. Leer deaktiviert die Signierung.

Für die vollständige Liste der Plugin-Optionen siehe Speicherung von Optionen und Einstellungen.

Betriebliche Hinweise

  • URLs werden mit filter_var( ..., FILTER_VALIDATE_URL ) validiert. Ungültige URLs werden stillschweigend übersprungen — hinterlegen Sie in Produktivumgebungen gültige https://-URLs.
  • Das Plugin löst nur Webhooks aus; es führt keine Zustellungswarteschlange, kein Protokoll über gesendete Webhooks und keinen Dead-Letter-Speicher. Wenn eine zuverlässige, reihenfolgegetreue Zustellung für Ihren Anwendungsfall kritisch ist, leiten Sie den Empfänger über eine Queue-Schicht (z. B. eine Serverless-Funktion mit integrierter Retry-Queue).
  • 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 die oben gezeigten wenigen Felder. Zusätzliche Lead-Metadaten sind über die WP-REST-API oder durch Abfrage des Post-Typs 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-Logs und das Error-Log Ihres Webservers.
  • Webhook kommt einmal an, aber keine Wiederholungsversuche — Der erste Versuch ist bewusst 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).
  • Signatur-Fehler beim Empfänger — Bestätigen Sie, dass beide Seiten exakt dasselbe Secret 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 Vollsynchronisation kann Ereignisse für bereits bekannte Fahrzeuge erneut auslösen. Siehe Import-Engine für die Regeln der Änderungserkennung.
  • Hängende Wiederholungsversuche — WP-Cron benötigt regelmässigen Website-Traffic, um ausgelöst zu werden. Konfigurieren Sie auf Websites mit wenig Traffic einen echten Cronjob oder den REST-Cron-Endpunkt, wie in Cron-Ereignisse und Scheduler beschrieben.

Verwandte Dokumente