Webhook-Ereignis-Referenz

Dieser Anhang beschreibt die ausgehenden Webhook-Ereignisse, die vom ADP Car Market Hub-Plugin ausgelöst werden.

Wann Sie dieses Dokument verwenden sollten

Verwenden Sie diese Referenz, wenn Sie einen Empfänger erstellen, Signaturen überprüfen oder eine Integration dokumentieren. Die konzeptionelle Beschreibung finden Sie unter Webhooks.

Übersicht

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

• new_lead — wenn eine Kontaktformular-Einsendung als Lead gespeichert wird.
• new_import — wenn ein Fahrzeug während eines Imports erstellt oder aktualisiert wird.

Jedes Ereignis ist ein JSON-POST an eine vom Administrator konfigurierte URL. Wenn ein Shared Secret konfiguriert ist, enthält die Anfrage auch einen HMAC-SHA256-Signatur-Header, mit dem der Empfänger die Payload verifizieren kann.

Die Ereignisse sind unabhängig voneinander: Die Konfiguration einer URL aktiviert nicht die andere. Wenn eine URL leer gelassen wird, wird dieses Ereignis vollständig deaktiviert.

Hinweis zum aktuellen Verhalten: In der aktuellen Plugin-Version wird tatsächlich nur new_import gesendet. Der new_lead-Übertragungsweg ist vorhanden (Empfänger, Signierung und die Option as24ci_webhook_url_new_lead existieren alle), aber sein Trigger wird im aktuellen Code nicht ausgelöst. Die Konfiguration einer new_lead-URL führt daher noch nicht zu Anfragen. Verlassen Sie sich bei Lead-Benachrichtigungen heute auf die Lead-E-Mails (siehe Leads-Referenz). Das folgende Schema dokumentiert die geplante new_lead-Payload für Empfänger, die darauf vorbereitet sein möchten.

Ereignis-Übersicht

Ein Shared Signing Secret wird global über as24ci_webhook_secret konfiguriert.

Payload-Format

Alle Payloads sind JSON-Objekte mit event, timestamp (ISO 8601, UTC) und einem ereignisspezifischen Datenblock.

new_lead

{
  "event": "new_lead",
  "timestamp": "2025-01-01T12:00:00+00:00",
  "lead_id": 0,
  "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": 0,
  "listing_id": "",
  "data": {
    "title": "",
    "url": "",
    "make": "",
    "model": "",
    "price": 0
  }
}

Die Payload new_import wird sowohl bei neuen Einfügungen als auch bei Aktualisierungen ausgelöst. Der Hook-Callback erhält intern ein Flag is_update; die ausgehende Payload selbst enthält dieses Flag in der aktuellen Plugin-Version nicht. Prüfen Sie vor der Veröffentlichung anhand des aktuellen Quellcodes, ob Ihre Integration eine Unterscheidung der beiden Fälle erfordert.

Signatur-Verifizierung

Wenn 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 Verifizierung auf Empfängerseite:

1. Lesen Sie den rohen Anfragetext ein, ohne ihn neu zu codieren.
2. Berechnen Sie hash_hmac('sha256', body, secret) mit demselben Shared Secret.
3. Vergleichen Sie das Ergebnis mit X-AS24CI-Signature unter Verwendung eines Constant-Time-Vergleichs (zum Beispiel hash_equals in PHP).

Wenn kein Secret konfiguriert ist, wird der Header X-AS24CI-Signature nicht gesendet. In Produktionsumgebungen 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 etwa 60 Sekunden später ein nachfolgendes Cron-Ereignis (as24ci_webhook_retry), das einen blockierenden Neuversand durchführt, damit der Antwortcode überprüft werden kann.
• Bei Verbindungsfehlern oder HTTP-5xx 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 Aufgaben idealerweise asynchron abarbeiten.

Konfiguration

URLs werden mit filter_var( ..., FILTER_VALIDATE_URL ) validiert. Ungültige URLs werden stillschweigend übersprungen — richten Sie in Produktionsumgebungen gültige https://-URLs ein.

Betriebshinweise

• Das Plugin löst nur Webhooks aus; es verwaltet keine Zustellungswarteschlange, kein Replay-Protokoll und keinen Dead-Letter-Speicher. Wenn eine zuverlässige, geordnete Zustellung für Ihren Anwendungsfall kritisch ist, betreiben Sie den Empfänger hinter einer Queue-Schicht.
• Jeder Webhook wird aus derselben WordPress-Anfrage heraus ausgelöst, die das Quellereignis generiert hat. Langsame Empfänger blockieren die benutzerseitige Anfrage nicht, da der erste Versuch nicht-blockierend ist.
• Die Payload new_lead enthält nur den oben gezeigten kleinen Satz an Feldern. Zusätzliche Lead-Metadaten können durch Abfrage des Post-Typs as24ci_lead mit normalen WordPress-Funktionen abgerufen werden.
• Die Payload new_import wird bewusst klein gehalten. Um den vollständigen Fahrzeugdatensatz abzurufen, rufen Sie /wp-json/as24ci/v1/vehicles/<post_id> ab (wenn die öffentliche REST-API aktiviert ist).

Fehlerbehebung

• Webhook kommt nie an. Stellen Sie sicher, dass die URL HTTPS verwendet, vom WordPress-Server aus erreichbar ist und als URL validiert wird. Überprüfen Sie die Plugin-Protokolle und das Webserver-Fehlerprotokoll.
• Webhook kommt einmal an, aber keine Wiederholungsversuche. Der erste Versuch ist absichtlich „Fire and Forget“; stellen Sie sicher, dass das Ereignis as24ci_webhook_retry geplant wird (es basiert auf WP-Cron oder Ihrem externen Cron).
• Signatur-Fehler auf Empfängerseite. Stellen Sie sicher, dass beide Seiten exakt dasselbe Secret verwenden und dass der Empfänger den rohen Anfragetext verifiziert, 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.
• Hängende Wiederholungsversuche. WP-Cron erfordert regelmäßigen Website-Traffic, um ausgelöst zu werden. Richten Sie auf Websites mit geringem Traffic einen echten Cron-Job oder den in der Cron-Hook-Referenz beschriebenen REST-Cron-Endpunkt ein.

Verwandte Dokumente

• Webhooks
• Webhook-Integration
• REST-Endpunkt-Referenz
• Cron-Hook-Referenz
• Einstellungen-Referenz