Documentatie · Technische documentatie

Webhooks

Dit document beschrijft de uitgaande HTTP-webhooks die worden geactiveerd door de ADP Car Market Hub-plugin, zodat externe CRM-, notificatie- of automatiseringssystemen in realtime kunnen reageren op plugin-gebeurtenissen.

Wanneer u dit document moet gebruiken

Lees dit document als u:

  • De plugin wilt verbinden met een externe CRM- of notificatieservice (bijvoorbeeld een workflow-automatiseringstool) zodat nieuwe leads of nieuw geïmporteerde voertuigen acties in een ander systeem activeren.
  • Een ontvangend eindpunt wilt implementeren dat de authenticiteit van webhooks verifieert met behulp van de HMAC-handtekening.
  • Gemiste of gedupliceerde webhook-leveringen wilt diagnosticeren.

Voor inkomende HTTP, zie REST API-eindpunten.

Overzicht

De plugin kan twee uitgaande webhook-gebeurtenissen activeren:

  • new_lead — bedoeld om te worden geactiveerd wanneer een inzending van een contactformulier wordt opgeslagen als een lead-bericht. AS24CI\Webhooks luistert naar de as24ci_lead_saved-actie, maar in de huidige plugin-versie wordt die actie nergens in de code verzonden (de lead wordt opgeslagen via Leads_CPT::save_lead() zonder de hook te activeren), dus de new_lead-webhook wordt momenteel niet geactiveerd. Behandel deze gebeurtenis als slapend totdat het activeringspunt is hersteld.
  • new_import — geactiveerd wanneer een voertuig wordt aangemaakt of bijgewerkt tijdens een import (via de as24ci_vehicle_imported-actie). Deze gebeurtenis is actief.

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

Webhooks zijn onafhankelijk: het configureren van de ene activeert de andere niet. Als u een URL leeg laat, wordt die gebeurtenis volledig uitgeschakeld.

Vereisten of randvoorwaarden

  • Een bereikbaar HTTPS-eindpunt aan de ontvangende kant.
  • (Optioneel maar ten zeerste aanbevolen) een gedeeld geheim opgeslagen in de plugin-instellingen en op de ontvanger, gebruikt om de handtekening te verifiëren.
  • Voor de new_lead-gebeurtenis: let op de bovenstaande waarschuwing — de as24ci_lead_saved-actie wordt momenteel niet verzonden, dus deze gebeurtenis zal in de huidige plugin-versie niet worden geactiveerd, zelfs niet als er een URL is geconfigureerd.
  • Voor de new_import-gebeurtenis: de import-engine moet geconfigureerd zijn en draaien. Zie Import-engine.

Stapsgewijze instructies

  1. Open het plugin-beheer en zoek de webhook-velden. Deze staan op het tabblad Leads als de invoervelden met de labels New lead webhook URL, New import webhook URL en Webhook secret.
  2. Voer een geldige https://-URL in voor elke gebeurtenis die u wilt ontvangen.
  3. Genereer een sterk willekeurig geheim (bijvoorbeeld een reeks van 32+ tekens) en plak dit in het veld Webhook secret. Configureer dezelfde waarde op de ontvanger.
  4. Sla de instellingen op. De plugin slaat de waarden op in de opties as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import en as24ci_webhook_secret.
  5. Activeer een testgebeurtenis: - Voor new_lead: dien een testcontactformulier in op de frontend. - Voor new_import: voer een import uit die ten minste één voertuig aanmaakt of bijwerkt.
  6. Bevestig de ontvangst en de verificatie van de handtekening aan de ontvangende kant.

Payload-referentie

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

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

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

Authenticatie en handtekeningverificatie

Wanneer de optie 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 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 met X-AS24CI-Signature met behulp van een vergelijking in constante tijd (bijv. hash_equals in PHP).

Als er geen geheim is geconfigureerd, wordt de X-AS24CI-Signature-header niet verzonden. Productie-omgevingen 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 een vervolg-cron-gebeurtenis (as24ci_webhook_retry) ongeveer 60 seconden later die een blokkerende herverzending uitvoert, zodat de responscode kan worden gecontroleerd.
  • Als de respons een verbindingsfout of HTTP 5xx is, plant de plugin extra herpogingen met exponentiële backoff (~2 minuten, daarna ~4 minuten), tot een maximum van drie pogingen in totaal.
  • HTTP 4xx-responsen worden behandeld als definitief en worden niet opnieuw geprobeerd; los het probleem op de ontvanger op en activeer de brongebeurtenis indien nodig opnieuw.
  • Ontvangers moeten binnen 15 seconden reageren en idealiter zwaar werk asynchroon uitvoeren.

Configuratiereferentie

OptiesleutelOpgeslagen waarde
as24ci_webhook_url_new_leadURL aangeroepen voor de new_lead-gebeurtenis. Leeg schakelt de gebeurtenis uit.
as24ci_webhook_url_new_importURL aangeroepen voor de new_import-gebeurtenis. Leeg schakelt de gebeurtenis uit.
as24ci_webhook_secretGedeeld geheim dat wordt gebruikt om payloads te ondertekenen. Leeg schakelt ondertekening uit.

Voor de volledige lijst met plugin-opties, zie Opslag van opties en instellingen.

Operationele opmerkingen

  • URL's worden gevalideerd met filter_var( ..., FILTER_VALIDATE_URL ). Ongeldige URL's worden stilletjes overgeslagen — stel geldige https://-URL's in in productie.
  • De plugin activeert alleen webhooks; hij onderhoudt geen leveringswachtrij, afspeellogboek of dead-letter-opslag. Als betrouwbare, geordende levering cruciaal is voor uw use-case, leid de ontvanger dan door een wachtrijlaag (bijvoorbeeld een serverloze functie met een ingebouwde herpogingswachtrij).
  • 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 new_lead-payload bevat alleen de kleine set velden die hierboven wordt getoond. Aanvullende lead-metadata is beschikbaar via de WP REST API of door het post-type as24ci_lead op te vragen met normale WordPress-functies.
  • De new_import-payload 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 uw webserver.
  • Webhook komt één keer aan maar geen herpogingen — de eerste poging is bewust fire-and-forget; controleer of de as24ci_webhook_retry-gebeurtenis wordt gepland (deze is afhankelijk van WP-Cron of uw externe cron).
  • Handtekening komt niet overeen op de ontvanger — bevestig dat beide kanten exact hetzelfde geheim gebruiken, en dat de ontvanger de ruwe verzoekbody verifieert zonder deze opnieuw te serialiseren of mooi op te maken (pretty-print) voordat de hash wordt berekend.
  • Dubbele new_import-leveringen — wijzigingsdetectie slaat voertuigen over waarvan de payload ongewijzigd is, maar een geforceerde volledige synchronisatie kan gebeurtenissen opnieuw verzenden voor reeds bekende advertenties. Zie Import-engine voor de regels voor wijzigingsdetectie.
  • Vastgelopen herpogingen — WP-Cron vereist regelmatig siteverkeer om te worden geactiveerd. Configureer op sites met weinig verkeer een echte cronjob of het REST-cron-eindpunt beschreven in Cron-gebeurtenissen en planner.

Gerelateerde documenten