Documentatie · Integratiehandleiding

Webhook-integratie

Dit document legt uit hoe de uitgaande webhooks van de ADP Car Market Hub-plugin werken, hoe u ze veilig configureert, hoe een ontvangend systeem de payloads moet valideren en wat u operationeel kunt verwachten. Het behandelt ook de beperkingen van de huidige implementatie, zodat integraties hieromheen kunnen worden ontworpen.

Wanneer u dit document moet gebruiken

Gebruik dit document als u:

De plugin koppelt aan een CRM, leadrouting-tool, meldingsservice of workflow-automatiseringsplatform.
Het ontvangende eindpunt bouwt of beheert dat de plugin moet aanroepen.
De beveiligingsstatus van een webhook-integratie beoordeelt.
Problemen oplost met een ontvanger die niet lijkt te worden aangeroepen of die payloads weigert.

De doelgroep is een integrator of ontwikkelaar die aan het ontvangende systeem werkt, samen met de WordPress-beheerder die de plugin configureert.

Overzicht

Een webhook is een uitgaand HTTP-verzoek dat de plugin naar een URL van uw keuze stuurt wanneer er een specifieke gebeurtenis plaatsvindt op de WordPress-site. De plugin verzendt een JSON-document dat de gebeurtenis beschrijft; het ontvangende systeem verwerkt dit naar eigen inzicht (een CRM-ticket aanmaken, een chatbericht plaatsen, toevoegen aan een spreadsheet, een lead doorsturen, enzovoort).

De plugin biedt momenteel twee gebeurtenissen:

new_lead — geactiveerd wanneer een bezoeker het contactformulier op een voertuigpagina verzendt en een lead wordt opgeslagen.
new_import — geactiveerd wanneer een voertuig wordt geïmporteerd of bijgewerkt door de importer.

Opmerking over huidig gedrag: In de huidige plugin-versie wordt alleen new_import daadwerkelijk verzonden. Het pad voor new_lead is wel voorbereid (doel-URL, geheim en ondertekening werken allemaal), maar de trigger is in de huidige code nog niet actief. Een geconfigureerde new_lead-URL zal dus nog geen verzoeken ontvangen. Gebruik in de tussentijd de ingebouwde lead-e-mails voor leadmeldingen, en configureer new_lead nu alvast als u wilt dat de ontvanger klaar is voor wanneer deze wordt geactiveerd.

Elke gebeurtenis heeft zijn eigen configureerbare doel-URL. Er kan een gedeeld geheim worden geconfigureerd om elke payload te ondertekenen met HMAC-SHA256, zodat de ontvanger kan controleren of het verzoek daadwerkelijk van de plugin afkomstig is.

Webhooks zijn optioneel. Als er geen doel-URL is geconfigureerd, wordt er voor die gebeurtenis geen verzoek verzonden.

Systeemvereisten

Bereid het volgende voor voordat u webhooks configureert:

Een ontvangend eindpunt dat een HTTPS POST-verzoek met een JSON-body accepteert. HTTPS wordt ten zeerste aanbevolen; een HTTP-eindpunt stelt de payload tijdens de overdracht bloot.
Kennis van hoe de ontvanger reageert op fouten, zodat het hieronder beschreven retry-gedrag logisch is voor uw installatie.
Een gedeelde geheime waarde die u zowel in de plugin als in de ontvanger kunt configureren (alleen vereist als u handtekeningverificatie wilt — ten zeerste aanbevolen).
WordPress-beheerderstoegang op de site waarop de plugin draait.

Stapsgewijze instructies

Bepaal welke gebeurtenissen u wilt doorsturen. U kunt new_lead, new_import of beide configureren. Laat een doel-URL leeg om die gebeurtenis uit te schakelen.
Kies een gedeeld geheim. Gebruik een lange, willekeurige tekenreeks (bijvoorbeeld een gegenereerd wachtwoord uit uw wachtwoordbeheerder). Houd dit geheim — het mag nooit openbaar worden gemaakt.
Open de plugin-instellingen. Navigeer naar Car Market Hub → Leads. De sectie Webhooks op het tabblad Leads bevat de velden New lead webhook URL, New import webhook URL en Webhook secret. Controleer de exacte plaatsing in de huidige plugin-versie, aangezien de indeling van de gebruikersinterface tussen releases kan veranderen.
Configureer de URL's. Plak de ontvangende URL's in de bijbehorende velden. De plugin controleert of de waarde een syntactisch correcte URL is en slaat de verzending over als deze ontbreekt of ongeldig is.
Configureer het geheim. Plak het gedeelde geheim in het veld Webhook secret. Configureer dezelfde waarde in de ontvanger.
Sla op en activeer een test. Sla de instellingen op en activeer vervolgens een echte gebeurtenis: - Voor new_lead: vul het leadformulier in op een voertuigdetailpagina vanuit een privévenster. - Voor new_import: voer de importer uit (handmatig of wacht op de volgende geplande uitvoering) zodat er ten minste één voertuig wordt toegevoegd of bijgewerkt.
Bevestig de ontvangst. Controleer de logs van de ontvanger om te bevestigen dat het verzoek is aangekomen en de handtekening met succes is geverifieerd. Als er iets mis is, raadpleeg dan Problemen oplossen hieronder.

Configuratiereferentie

Instelling	Doel
New lead webhook URL	Eindpunt dat wordt aangeroepen wanneer een verzonden contactformulier als lead wordt opgeslagen.
New import webhook URL	Eindpunt dat wordt aangeroepen wanneer een voertuig wordt geïmporteerd of bijgewerkt door de importer.
Webhook secret	Gedeeld geheim dat wordt gebruikt om elke payload te ondertekenen met HMAC-SHA256. Wanneer dit leeg is, wordt er geen handtekening-header verzonden.

De bijbehorende optiesleutels die intern door de plugin worden gebruikt, zijn gedocumenteerd in Option Keys and Settings Storage en de Webhook Event Reference.

Verzoeksindeling

De plugin verzendt elke gebeurtenis als een HTTPS POST-verzoek met een JSON-body en de volgende headers:

Content-Type: application/json
X-AS24CI-Signature: <hex> — alleen aanwezig wanneer er een webhook-geheim is geconfigureerd. De waarde is de HMAC-SHA256 van de ruwe verzoekbody, met het geconfigureerde geheim als sleutel, gecodeerd als een hexadecimale tekenreeks in kleine letters.

De exacte set velden in de JSON-body kan tussen plugin-versies veranderen. De referentie voor de huidige versie is de Webhook Event Reference. Beide gebeurtenissen bevatten minimaal:

event — de naam van de gebeurtenis (new_lead of new_import).
timestamp — een ISO-8601 tijdstempel in UTC van wanneer de gebeurtenis is voorbereid.
Een identificatie voor het gerelateerde WordPress-object (lead-ID voor new_lead, post-ID en listing-ID voor new_import).
Een data-object met een kleine set samenvattende velden over de gebeurtenis (basis leadvelden voor new_lead; basis voertuigvelden voor new_import).

Ontvangers moeten onbekende velden behandelen als voorwaarts compatibele toevoegingen en ze negeren in plaats van de payload te weigeren. Controleer de huidige set velden met het referentiedocument voordat u uw integratie live zet.

Inkomende verzoeken valideren

Wanneer er een webhook-geheim is geconfigureerd, moet de ontvanger altijd de handtekening controleren voordat de payload wordt vertrouwd. De verificatieregel is:

Lees de ruwe verzoekbody vóór eventuele JSON-parsing (het parsen en opnieuw serialiseren kan de bytevolgorde of witruimte veranderen en de handtekening ongeldig maken).
Bereken HMAC-SHA256(raw_body, shared_secret) en codeer het resultaat als een hexadecimale tekenreeks in kleine letters.
Vergelijk dit met de waarde van de X-AS24CI-Signature-header met behulp van een vergelijking in constante tijd (de meeste talen bieden dit aan als hash_equals, crypto.timingSafeEqual, hmac.compare_digest of vergelijkbaar).
Weiger het verzoek met 401 als de handtekening ontbreekt of niet overeenkomt.

Aanvullende defensieve controles die de ontvanger kan overwegen:

Weiger HTTP. Accepteer alleen HTTPS-verzoeken op de ontvanger.
Zet het IP-adres van de bron op een whitelist van de WordPress-site op netwerk- of applicatieniveau, naast de handtekeningcontrole.
Idempotentie. Dezelfde logische gebeurtenis kan vaker dan eens worden afgeleverd (zie Aflevergedrag hieronder). Gebruik de lead-ID, de post-ID, de listing-ID of een hash van de payload om te ontdubbelen aan de kant van de ontvanger.
Tijdstempelvenster. Weiger verzoeken waarvan de timestamp ver in het verleden of de toekomst ligt om het nut van herhaalde payloads te beperken. Een paar minuten tijdsverschil aan weerszijden is normaal.
Schematolerantie. Behandel extra velden als voorwaarts compatibel en onbekende gebeurtenisnamen als iets om te loggen in plaats van op vast te lopen.
Limiet voor body-grootte. Beperk de maximale body-grootte bij de ontvanger om te beschermen tegen misvormde invoer.

Als er geen geheim is geconfigureerd, heeft de ontvanger geen manier om te controleren of het verzoek echt van de plugin afkomstig is; configureer een geheim tenzij het netwerkpad volledig privé en vertrouwd is.

Aflevergedrag

De huidige implementatie heeft de volgende afleverkenmerken. Controleer deze gedragingen in de huidige plugin-versie voordat u er afhankelijk van wordt.

Eerste poging is fire-and-forget. Wanneer een gebeurtenis wordt geactiveerd, verzendt de plugin de eerste aflevering als een niet-blokkerende HTTP POST. Er wordt niet gewacht op het antwoord van de ontvanger en de responscode wordt bij deze poging niet geïnterpreteerd.
Geplande herpogingen. Kort na de eerste poging wordt een vervolgaflevering gepland via de taakwachtrij van WordPress. Als die aflevering een 5xx-respons of een verbindingsfout oplevert, plant de plugin verdere herpogingen met een korte, toenemende vertraging ertussen.
Limiet op herpogingen. De plugin blijft niet oneindig proberen. Na een klein aantal mislukte pogingen wordt de gebeurtenis geruisloos verwijderd en niet later alsnog afgeleverd.
Onafhankelijkheid per gebeurtenis. Een mislukte aflevering voor de ene gebeurtenis heeft geen invloed op de volgende gebeurtenis.
Volgorde is niet gegarandeerd. Twee gebeurtenissen die kort na elkaar worden geactiveerd, kunnen in willekeurige volgorde aankomen. Ontvangers moeten vertrouwen op identificaties en tijdstempels in de payload, niet op de volgorde van aankomst.
Model met één ontvanger. Elke gebeurtenis heeft exact één geconfigureerde URL. Om naar meerdere systemen door te sturen, configureert u een kleine doorstuurder (bijvoorbeeld een automatiseringsplatform zoals Zapier, Make, n8n of een zelfgehoste relay) als ontvanger en laat u deze doorsturen naar de downstream-systemen.
Cron-afhankelijkheid voor herpogingen. Herpogingen worden gepland via de taakwachtrij van WordPress. Zorg er bij installaties die de Server cron-modus gebruiken (zie Server Cron Setup) voor dat de bijbehorende taak die wp-cron.php aanroept actief is — anders worden geplande herpogingen niet uitgevoerd.

Operationele opmerkingen

Logboekregistratie aan de WordPress-zijde. De plugin logt API- en importactiviteiten in wp-content/uploads/as24ci-logs/. Webhook-aflevering maakt deel uit van de normale werking en genereert standaard mogelijk geen uitgebreide logs. De meest betrouwbare plek om te zien wat er is afgeleverd, is het logboek van de ontvanger zelf.
Logboekregistratie aan de kant van de ontvanger. Log elk ontvangen verzoek, inclusief de headers (met de handtekening) and de ruwe body, vóór eventuele verwerking. Dit maakt zowel incidentrespons als foutopsporing veel eenvoudiger. Pas de normale regels voor gegevensbescherming van de ontvanger toe — leads bevatten persoonsgegevens.
Persoonsgegevens. De new_lead-gebeurtenis bevat persoonsgegevens die door de bezoeker zijn ingediend (zoals naam, e-mailadres, telefoonnummer, bericht). Behandel de ontvanger als een gegevensverwerker voor deze informatie en pas uw normale privacyregels toe. Zie Lead Data and Consent en GDPR / DSGVO Notes.
Het geheim roteren. Wanneer u het webhook-geheim in de plugin wijzigt, moet u de ontvanger tegelijkertijd bijwerken. Totdat beide kanten overeenstemmen, zal elke aflevering worden geweigerd door de handtekeningcontrole.
De URL wijzigen. Het bijwerken van de URL wordt van kracht bij de volgende gebeurtenis. Er is geen ingebouwd mechanisme om historische gebeurtenissen opnieuw af te leveren.
Een webhook uitschakelen. Maak het URL-veld leeg en sla op. Er worden geen verdere gebeurtenissen van dat type meer verzonden.

Beperkingen

Alleen de twee hierboven beschreven gebeurtenissen worden verzonden. Er is geen ingebouwde gebeurtenis voor het verwijderen van voertuigen, wijzigingen in de leadstatus, aanmeldingen voor zoekalerts, proefritboekingen of andere plugin-acties.
Er is geen beheerinterface om individuele afleverpogingen te inspecteren of om historische gebeurtenissen opnieuw af te spelen.
Er is geen native distributie (fan-out) naar meerdere ontvangers per gebeurtenis.
Er is geen eindpunt voor inkomende webhooks — de plugin verzendt alleen webhooks; deze accepteert geen willekeurige inkomende webhooks.
Het aantal herpogingen en de vertragingen kunnen tussen plugin-versies veranderen. Controleer het huidige gedrag in de Webhook Event Reference voordat u klantgerichte documentatie publiceert.

Probleemoplossing

Symptoom	Waarschijnlijke oorzaak	Wat te controleren
Ontvanger ziet nooit een verzoek.	De webhook-URL is leeg, onjuist geformatteerd of onbereikbaar vanaf de WordPress-site (DNS, firewall, uitgaand HTTPS geblokkeerd).	Controleer de URL op het tabblad Leads opnieuw. Bevestig dat uitgaand HTTPS werkt vanaf de WordPress-host (zie API-, netwerk- en SSL-vereisten).
Ontvanger ziet het verzoek, maar de handtekening komt niet overeen.	De ontvanger verifieert de geparste body in plaats van de onbewerkte bytes, de secret verschilt aan beide kanten, of de vergelijking is niet constant-time.	Controleer of de onbewerkte body wordt gelezen vóór de JSON-parsing, of de secret exact overeenkomt (geen spaties, geen regeleinden) en of de vergelijking een constant-time functie gebruikt.
Ontvanger ziet het verzoek, maar `X-AS24CI-Signature` ontbreekt.	De webhook secret is leeg in de plugin-instellingen.	Stel een secret in, sla op en test opnieuw.
Inzendingen van leadformulieren komen aan bij de ontvanger, maar dezelfde lead wordt meerdere keren afgeleverd.	Verwacht gedrag: de plugin doet nieuwe pogingen wanneer een eerdere aflevering mislukt leek, en de eerste poging is fire-and-forget.	Maak de ontvanger idempotent met behulp van `lead_id` (of een andere stabiele identificator uit de payload).
`new_import`-events komen niet aan, hoewel er wel imports worden uitgevoerd.	De webhook-URL voor nieuwe imports is leeg of onjuist geconfigureerd.	Controleer de URL op het tabblad Leads opnieuw; verifieer met een handmatige import.
Er lijken geen nieuwe pogingen plaats te vinden.	WP-Cron is uitgeschakeld en er is geen bijbehorende `wp-cron.php` cron-job actief.	Zie Server Cron Setup en voeg de bijbehorende job toe.
Ontvanger retourneert herhaaldelijk `5xx` tijdens incidenten.	Normale foutmodus. De plugin probeert het een klein aantal keren opnieuw en geeft het daarna op voor dat event.	Maak de ontvanger tolerant of buffer aan de kant van de ontvanger. Er is geen ingebouwde beheerfunctie voor opnieuw afspelen.
De waarde van de webhook secret verschijnt in een log of screenshot.	Onvoldoende anonimisering/redactie.	Wijzig de secret onmiddellijk, update de plugin en de ontvanger, en test opnieuw.