Webhook-gebeurtenisreferentie

Deze bijlage beschrijft de uitgaande webhook-gebeurtenissen die worden geactiveerd door de ADP Car Market Hub plugin.

Wanneer u dit document moet gebruiken

Gebruik deze referentie bij het bouwen van een ontvanger, bij het verifiëren van handtekeningen of bij het documenteren van een integratie. Zie Webhooks voor de conceptuele beschrijving.

Overzicht

De plugin kan twee uitgaande webhook-gebeurtenissen activeren:

• new_lead — wanneer een inzending van een contactformulier wordt opgeslagen als een lead.
• new_import — wanneer een voertuig wordt aangemaakt of bijgewerkt tijdens een import.

Elke gebeurtenis is een JSON POST naar een URL die door de beheerder is geconfigureerd. Wanneer een gedeeld geheim is geconfigureerd, bevat het verzoek ook een HMAC-SHA256-handtekeningheader die de ontvanger kan gebruiken om de payload te verifiëren.

De gebeurtenissen zijn onafhankelijk: het configureren van de ene URL schakelt de andere niet in. Als u een URL leeg laat, wordt die gebeurtenis volledig uitgeschakeld.

Opmerking over het huidige gedrag: In de huidige plugin-versie wordt alleen new_import daadwerkelijk verzonden. Het leveringstraject voor new_lead is aanwezig (ontvanger, ondertekening en de optie as24ci_webhook_url_new_lead bestaan allemaal), maar de trigger wordt in de huidige code niet geactiveerd, dus het configureren van een new_lead-URL zal nog geen verzoeken opleveren. Vertrouw voor leadmeldingen momenteel op de lead-e-mails (zie Beheerdersreferentie voor Leads). Het onderstaande schema documenteert de beoogde new_lead-payload voor ontvangers die hierop voorbereid willen zijn.

Overzicht van gebeurtenissen

Een gedeeld ondertekeningsgeheim wordt globaal geconfigureerd via as24ci_webhook_secret.

Payload-indeling

Alle payloads zijn JSON-objecten met event, timestamp (ISO 8601, UTC) en een gebeurtenisspecifiek datablok.

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
  }
}

De payload voor new_import wordt geactiveerd voor zowel nieuwe toevoegingen als updates. De hook-callback ontvangt intern een is_update-vlag; de uitgaande payload zelf bevat deze vlag in de huidige plugin-versie niet. Controleer of uw integratie het onderscheid tussen de twee situaties vereist aan de hand van de huidige broncode voordat u deze publiceert.

Handtekeningverificatie

Wanneer as24ci_webhook_secret is ingesteld, voegt de plugin de volgende header toe:

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

De handtekening wordt berekend over de exacte JSON-body die in het verzoek is verzonden. Om dit te verifiëren op de ontvanger:

1. Lees de ruwe verzoekbody zonder deze opnieuw te coderen.
2. Bereken hash_hmac('sha256', body, secret) met behulp van hetzelfde gedeelde geheim.
3. Vergelijk het resultaat met X-AS24CI-Signature met behulp van een vergelijking in constante tijd (bijvoorbeeld hash_equals in PHP).

Als er geen geheim is geconfigureerd, wordt de header X-AS24CI-Signature niet verzonden. Productie-installaties moeten altijd een geheim configureren.

Levering, herpogingen en time-outs

• Verzoeken gebruiken wp_remote_post() met een time-out van 15 seconden.
• De eerste poging is niet-blokkerend ("fire and forget"). De plugin plant vervolgens ongeveer 60 seconden later een vervolg-cron-gebeurtenis (as24ci_webhook_retry) die een blokkerende herverzending uitvoert, zodat de responscode kan worden gecontroleerd.
• Bij verbindingsfouten of HTTP 5xx plant de plugin extra herpogingen met een exponentiële back-off (~2 minuten, daarna ~4 minuten), tot een maximum van in totaal drie pogingen.
• HTTP 4xx-antwoorden worden als definitief beschouwd en worden niet opnieuw geprobeerd; herstel de ontvanger en activeer de brongebeurtenis indien nodig opnieuw.
• Ontvangers moeten binnen 15 seconden reageren en zwaar werk idealiter asynchroon voltooien.

Configuratie

URL's worden gevalideerd met filter_var( ..., FILTER_VALIDATE_URL ). Ongeldige URL's worden stilletjes overgeslagen — stel geldige https://-URL's in voor productie.

Operationele opmerkingen

• De plugin activeert alleen webhooks; deze houdt geen leveringswachtrij, logboek van herhalingen of opslag voor onbestelbare berichten bij. Als een betrouwbare, geordende levering cruciaal is voor uw use-case, laat de ontvanger dan achter een wachtrijlaag draaien.
• Elke webhook wordt geactiveerd vanuit hetzelfde WordPress-verzoek dat de brongebeurtenis heeft gegenereerd. Trage ontvangers zullen het gebruikersgerichte verzoek niet vertragen omdat de eerste poging niet-blokkerend is.
• De payload voor new_lead bevat alleen de kleine set velden die hierboven wordt getoond. Aanvullende lead-metadata is beschikbaar door het post-type as24ci_lead op te vragen met normale WordPress-functies.
• De payload voor new_import blijft bewust klein. Om het volledige voertuigrecord op te halen, haalt u /wp-json/as24ci/v1/vehicles/<post_id> op (wanneer de openbare REST API is ingeschakeld).

Probleemoplossing

• Webhook komt nooit aan. Controleer of de URL HTTPS is, bereikbaar is vanaf de WordPress-server en valideert als een URL. Controleer de plugin-logs en het foutenlogboek van de webserver.
• Webhook komt eenmalig aan maar er volgen geen herpogingen. De eerste poging is bewust fire-and-forget; controleer of de gebeurtenis as24ci_webhook_retry wordt ingepland (deze is afhankelijk van WP-Cron of uw externe cron).
• Handtekening komt niet overeen op de ontvanger. Controleer of beide partijen exact hetzelfde geheim gebruiken en of de ontvanger de ruwe verzoekbody verifieert zonder deze opnieuw te serialiseren of netjes op te maken (pretty-print) vóór het hashen.
• Dubbele leveringen van new_import. Wijzigingsdetectie slaat voertuigen over waarvan de payload ongewijzigd is, maar een geforceerde volledige synchronisatie kan gebeurtenissen voor reeds bekende advertenties opnieuw verzenden.
• Vastgelopen herpogingen. WP-Cron vereist regelmatig websiteverkeer om te starten. Configureer op websites met weinig verkeer een echte cronjob of het REST-cron-eindpunt zoals beschreven in de Cron Hook-referentie.

Gerelateerde documenten

• Webhooks
• Webhook-integratie
• REST-eindpuntreferentie
• Cron Hook-referentie
• Instellingenreferentie