Documentation · Documentation technique

Webhooks

Ce document décrit les webhooks HTTP sortants déclenchés par le plugin ADP Car Market Hub afin que les systèmes externes de CRM, de notification ou d'automatisation puissent réagir aux événements du plugin en temps réel.

Quand utiliser ce document

Lisez ce document si vous devez :

  • Connecter le plugin à un CRM externe ou à un service de notification (par exemple, un outil d'automatisation de flux de travail) afin que les nouveaux leads ou les véhicules nouvellement importés déclenchent des actions dans un autre système.
  • Implémenter un point de terminaison récepteur qui vérifie l'authenticité du webhook à l'aide de la signature HMAC.
  • Diagnostiquer les livraisons de webhooks manquées ou dupliquées.

Pour le protocole HTTP entrant, consultez les Points de terminaison de l'API REST.

Aperçu

Le plugin peut déclencher deux événements de webhook sortants :

  • new_lead — destiné à se déclencher lorsqu'une soumission de formulaire de contact est enregistrée en tant que publication de lead. AS24CI\Webhooks écoute l'action as24ci_lead_saved, mais dans la version actuelle du plugin, cette action n'est pas distribuée dans le code (le lead est enregistré via Leads_CPT::save_lead() sans déclencher le hook), de sorte que le webhook new_lead ne se déclenche pas actuellement. Considérez cet événement comme dormant jusqu'à ce que le point de déclenchement soit rétabli.
  • new_import — déclenché lorsqu'un véhicule est créé ou mis à jour lors d'une importation (via l'action as24ci_vehicle_imported). Cet événement est actif.

Chaque événement envoie une requête POST avec un payload JSON à une URL configurée par l'administrateur. Lorsqu'un secret partagé est configuré, chaque requête porte également un en-tête de signature HMAC-SHA256 que le récepteur peut utiliser pour vérifier le payload.

Les webhooks sont indépendants : la configuration de l'un n'active pas l'autre. Laisser une URL vide désactive complètement cet événement.

Configuration requise ou prérequis

  • Un point de terminaison HTTPS accessible du côté récepteur.
  • (Optionnel mais fortement recommandé) un secret partagé stocké dans les réglages du plugin et sur le récepteur, utilisé pour vérifier la signature.
  • Pour l'événement new_lead : notez la mise en garde ci-dessus — l'action as24ci_lead_saved n'est pas distribuée actuellement, cet événement ne se déclenchera donc pas dans la version actuelle du plugin, même si une URL est configurée.
  • Pour l'événement new_import : le moteur d'importation doit être configuré et opérationnel. Consultez le Moteur d'importation.

Instructions étape par étape

  1. Ouvrez l'administration du plugin et localisez les champs de webhook. Ils sont exposés sur l'onglet Leads sous la forme de champs de saisie intitulés New lead webhook URL, New import webhook URL et Webhook secret.
  2. Saisissez une URL https:// valide pour chaque événement que vous souhaitez recevoir.
  3. Générez un secret aléatoire fort (par exemple, une chaîne de plus de 32 caractères) et collez-le dans le champ Webhook secret. Configurez la même valeur sur le récepteur.
  4. Enregistrez les réglages. Le plugin stocke les valeurs dans les options as24ci_webhook_url_new_lead, as24ci_webhook_url_new_import et as24ci_webhook_secret.
  5. Déclenchez un événement de test : - Pour new_lead : soumettez un formulaire de contact de test sur le front-end. - Pour new_import : lancez une importation qui crée ou met à jour au moins un véhicule.
  6. Confirmez la réception et la vérification de la signature du côté du récepteur.

Référence du payload

Tous les payloads sont des objets JSON avec event, timestamp (ISO 8601, UTC) et un bloc de données spécifique à event.

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

Le payload new_import est déclenché à la fois pour les nouvelles insertions et pour les mises à jour. Le rappel du hook reçoit un indicateur is_update en interne ; le payload sortant lui-même n'inclut pas cet indicateur dans la version actuelle du plugin. Vérifiez si votre intégration nécessite de distinguer les deux cas et confirmez le comportement actuel par rapport au code source avant de publier des formulations destinées aux clients.

Authentification et vérification de la signature

Lorsque l'option as24ci_webhook_secret est définie, le plugin ajoute l'en-tête :

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

La signature est calculée sur le corps JSON exact envoyé dans la requête. Pour vérifier sur le récepteur :

  1. Lisez le corps brut de la requête sans le ré-encoder.
  2. Calculez hash_hmac('sha256', body, secret) en utilisant le même secret partagé.
  3. Comparez avec X-AS24CI-Signature en utilisant une comparaison en temps constant (par exemple, hash_equals en PHP).

Si aucun secret n'est configuré, l'en-tête X-AS24CI-Signature n'est pas envoyé. Les déploiements en production doivent toujours configurer un secret.

Livraison, tentatives et délais d'expiration

  • Les requêtes utilisent wp_remote_post() avec un délai d'expiration de 15 secondes.
  • La première tentative est non bloquante (fire and forget). Le plugin planifie ensuite un événement cron de suivi (as24ci_webhook_retry) environ 60 secondes plus tard qui effectue un renvoi bloquant afin que le code de réponse puisse être inspecté.
  • Si la réponse est une erreur de connexion ou un code HTTP 5xx, le plugin planifie des tentatives supplémentaires avec un intervalle exponentiel (~2 minutes, puis ~4 minutes), jusqu'à un maximum de trois tentatives au total.
  • Les réponses HTTP 4xx sont traitées comme définitives et ne font pas l'objet d'une nouvelle tentative ; corrigez le récepteur et redéclenchez l'événement source si nécessaire.
  • Les récepteurs doivent répondre dans les 15 secondes et, idéalement, effectuer tout travail lourd de manière asynchrone.

Référence de configuration

Clé d'optionValeur stockée
as24ci_webhook_url_new_leadURL appelée pour l'événement new_lead. Vide désactive l'événement.
as24ci_webhook_url_new_importURL appelée pour l'événement new_import. Vide désactive l'événement.
as24ci_webhook_secretSecret partagé utilisé pour signer les payloads. Vide désactive la signature.

Pour la liste complète des options du plugin, consultez Stockage des options et des réglages.

Notes opérationnelles

  • Les URL sont validées avec filter_var( ..., FILTER_VALIDATE_URL ). Les URL invalides sont ignorées silencieusement — définissez des URL https:// valides en production.
  • Le plugin ne fait que déclencher des webhooks ; il ne maintient pas de file d'attente de livraison, de journal de relecture ou de stockage des messages non distribués. Si une livraison fiable et ordonnée est essentielle pour votre cas d'utilisation, faites passer le récepteur par une couche de file d'attente (par exemple, une fonction serverless avec une file d'attente de tentatives intégrée).
  • Chaque webhook est déclenché à partir de la même requête WordPress qui a généré l'événement source. Les récepteurs lents ne bloqueront pas la requête de l'utilisateur car la première tentative est non bloquante.
  • Le payload new_lead ne comprend que le petit ensemble de champs présenté ci-dessus. Des métadonnées de lead supplémentaires sont disponibles via l'API REST de WordPress ou en interrogeant le type de publication as24ci_lead avec les fonctions normales de WordPress.
  • Le payload new_import reste intentionnellement de petite taille. Pour récupérer l'enregistrement complet du véhicule, récupérez /wp-json/as24ci/v1/vehicles/<post_id> (lorsque l'API REST publique est activée).

Dépannage

  • Le webhook n'arrive jamais — vérifiez que l'URL est en HTTPS, accessible depuis le serveur WordPress et validée en tant qu'URL. Vérifiez les journaux du plugin et le journal d'erreurs de votre serveur web.
  • Le webhook arrive une fois mais pas de tentative de rejeu — la première tentative est intentionnellement de type « envoyer et oublier » ; vérifiez que l'événement as24ci_webhook_retry est bien planifié (il repose sur WP-Cron ou votre cron externe).
  • Incohérence de signature sur le récepteur — confirmez que les deux parties utilisent exactement le même secret, et que le récepteur vérifie le corps brut de la requête sans le re-sérialiser ou le reformater avant le hachage.
  • Livraisons de new_import dupliquées — la détection des modifications ignore les véhicules dont le payload est inchangé, mais une synchronisation complète forcée peut réémettre des événements pour des annonces déjà connues. Consultez le Moteur d'importation pour connaître les règles de détection des modifications.
  • Tentatives bloquées — WP-Cron nécessite un trafic régulier sur le site pour se déclencher. Sur les sites à faible trafic, configurez une tâche cron réelle ou le point de terminaison cron REST décrit dans Événements Cron et planificateur.

Documents connexes