Webhook-Event-Referenz

Dieser Anhang beschreibt die ausgehenden Webhook-Events, 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. Für die konzeptionelle Beschreibung siehe Webhooks.

Übersicht

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

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

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

Die Events sind unabhängig voneinander: Die Konfiguration einer URL aktiviert die andere nicht. Wenn eine URL leer gelassen wird, wird das entsprechende Event vollständig deaktiviert.

Hinweis zum aktuellen Verhalten: In der aktuellen Plugin-Version wird tatsächlich nur new_import gesendet. Der Auslieferungspfad für new_lead 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. Daher führt die Konfiguration einer new_lead-URL noch zu keinen Anfragen. Verlassen Sie sich für 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.

Event-Ü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 eventspezifischen 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 dem Empfänger:

1. Lesen Sie den rohen Anfrage-Body 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 zeitkonstanten 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.

Auslieferung, 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-Event (as24ci_webhook_retry), das einen blockierenden Neuversuch 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 Quell-Event bei Bedarf erneut aus.
• Empfänger sollten innerhalb von 15 Sekunden antworten und rechenintensive Arbeiten idealerweise asynchron abwickeln.

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.

Betriebliche Hinweise

• Das Plugin löst nur Webhooks aus; es verwaltet keine Auslieferungswarteschlange, kein Replay-Log und keinen Dead-Letter-Speicher. Wenn eine zuverlässige, geordnete Auslieferung für Ihren Anwendungsfall kritisch ist, betreiben Sie den Empfänger hinter einer Queue-Schicht.
• Jeder Webhook wird aus derselben WordPress-Anfrage ausgelöst, die das Quell-Event generiert hat. Langsame Empfänger blockieren die benutzerseitige Anfrage nicht, da der erste Versuch nicht-blockierend ist.
• Die Payload new_lead enthält nur die oben gezeigten wenigen Felder. Zusätzliche Lead-Metadaten sind durch Abfrage des Post-Typs as24ci_lead mit normalen WordPress-Funktionen verfügbar.
• Die 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. Stellen Sie sicher, dass 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 des Webservers.
• Webhook kommt einmal an, aber keine Wiederholungsversuche. Der erste Versuch ist absichtlich „Fire and Forget“; stellen Sie sicher, dass das Event as24ci_webhook_retry geplant wird (es basiert auf WP-Cron oder Ihrem externen Cron).
• Signatur-Fehler auf dem Empfänger. Bestätigen Sie, dass beide Seiten exakt dasselbe Secret verwenden und dass der Empfänger den rohen Anfrage-Body verifiziert, ohne ihn vor dem Hashing neu zu serialisieren oder zu formatieren.
• Doppelte new_import-Auslieferungen. Die Änderungserkennung überspringt Fahrzeuge, deren Payload unverändert ist, aber eine erzwungene Vollsynchronisation kann Events für bereits bekannte Inserate erneut auslösen.
• Hängende Wiederholungsversuche. WP-Cron benötigt regelmässigen Website-Traffic, um ausgelöst zu werden. Richten Sie auf Websites mit wenig Traffic einen echten Cronjob oder den in Cron Hook Reference beschriebenen REST-Cron-Endpunkt ein.

Verwandte Dokumente

• Webhooks
• Webhook Integration
• REST Endpoint Reference
• Cron Hook Reference
• Settings Reference