Intégration des Webhooks

--- This document explains how the ADP Car Market Hub plugin's outgoing webhooks work, how to configure them safely, how a receiving system should validate the payloads, and what to expect operationally. It also covers the limitations of the current implementation so that integrations can be designed around them.

Quand utiliser ce document

Utilisez ce document si vous :

• Connectez l'extension à un CRM, un outil de routage de leads, un service de notification ou une plateforme d'automatisation de flux de travail.
• Créez ou gérez le point de terminaison de réception que l'extension doit appeler.
• Examinez la posture de sécurité d'une intégration de webhook.
• Dépannez un récepteur qui ne semble pas être appelé ou qui rejette les charges utiles.

Le public cible est un intégrateur ou un développeur travaillant sur le système de réception, ainsi que l'administrateur WordPress qui configure l'extension.

Aperçu

Un webhook est une requête HTTP sortante que l'extension envoie à une URL de votre choix lorsqu'un événement spécifique se produit sur le site WordPress. L'extension publie un document JSON décrivant l'événement ; le système de réception le traite comme il le souhaite (création d'un ticket CRM, publication d'un message de discussion, ajout à une feuille de calcul, routage d'un lead, etc.).

L'extension expose actuellement deux événements :

• new_lead — déclenché lorsqu'un visiteur soumet le formulaire de contact sur une page de véhicule et qu'un lead est enregistré.
• new_import — déclenché lorsqu'un véhicule est importé ou mis à jour par l'importateur.

Note sur le comportement actuel : Dans la version actuelle de l'extension, seul new_import est réellement envoyé. Le chemin new_lead est câblé (l'URL cible, le secret et la signature fonctionnent tous) mais son déclencheur n'est pas actif dans le code actuel, de sorte qu'une URL new_lead configurée ne recevra pas encore de requêtes. Utilisez en attendant les e-mails de lead intégrés pour les notifications de leads, et configurez new_lead dès maintenant si vous souhaitez que le récepteur soit prêt lorsqu'il sera activé.

Chaque événement possède sa propre URL cible configurable. Un secret partagé unique peut être configuré pour signer chaque charge utile avec HMAC-SHA256, afin que le récepteur puisse vérifier que la requête provient bien de l'extension.

Les webhooks sont facultatifs. Si aucune URL cible n'est configurée, aucune requête n'est envoyée pour cet événement.

Prérequis

Avant de configurer les webhooks, préparez :

• Un point de terminaison de réception qui accepte une requête HTTPS POST avec un corps JSON. Le protocole HTTPS est fortement recommandé ; un point de terminaison HTTP expose la charge utile en transit.
• La connaissance de la manière dont le récepteur répond aux erreurs, afin que le comportement de tentative décrit ci-dessous soit cohérent avec votre configuration.
• Une valeur de secret partagé que vous pouvez configurer à la fois dans l'extension et dans le récepteur (uniquement requis si vous souhaitez une vérification de signature — fortement recommandé).
• Un accès administrateur WordPress sur le site qui exécute l'extension.

Instructions étape par étape

1. Décidez quels événements transférer. Vous pouvez configurer l'un ou l'autre de new_lead et new_import, ou les deux. Laissez une URL cible vide pour désactiver cet événement.
2. Choisissez un secret partagé. Utilisez une chaîne longue et aléatoire (par exemple, un mot de passe généré par votre gestionnaire de mots de passe). Gardez-le confidentiel — il ne doit jamais être publié.
3. Ouvrez les réglages de l'extension. Accédez à Car Market Hub → Leads. La section Webhooks de l'onglet Leads contient les champs New lead webhook URL, New import webhook URL et Webhook secret. Vérifiez l'emplacement exact dans la version actuelle de l'extension, car le regroupement de l'interface utilisateur peut évoluer d'une version à l'autre.
4. Configurez les URL. Collez les URL de réception dans les champs correspondants. L'extension valide que la valeur est une URL syntaxiquement correcte et ignore la livraison si elle est manquante ou invalide.
5. Configurez le secret. Collez le secret partagé dans le champ Webhook secret. Configurez la même valeur dans le récepteur.
6. Enregistrez et déclenchez un test. Enregistrez les réglages, puis déclenchez un événement réel : - Pour new_lead : soumettez le formulaire de lead sur une page de détails de véhicule depuis une fenêtre de navigation privée. - Pour new_import : lancez l'importateur (manuellement ou attendez la prochaine exécution planifiée) afin qu'au moins un véhicule soit inséré ou mis à jour.
7. Confirmez la réception. Vérifiez les journaux du récepteur pour confirmer que la requête est arrivée et que la signature a été vérifiée avec succès. Si quelque chose ne va pas, consultez la section Dépannage ci-dessous.

Référence de configuration

Les clés d'option correspondantes utilisées en interne par l'extension sont documentées dans Option Keys and Settings Storage et Webhook Event Reference.

Format de la requête

L'extension envoie chaque événement sous forme de requête HTTPS POST avec un corps JSON et les en-têtes suivants :

• Content-Type: application/json
• X-AS24CI-Signature: <hex> — présent uniquement lorsqu'un secret de webhook est configuré. La valeur est le HMAC-SHA256 du corps brut de la requête, en utilisant le secret configuré comme clé, encodé sous forme de chaîne hexadécimale en minuscules.

L'ensemble exact de champs dans le corps JSON peut évoluer d'une version à l'autre de l'extension. La référence pour la version actuelle est Webhook Event Reference. Les deux événements incluent au minimum :

• event — le nom de l'événement (new_lead ou new_import).
• timestamp — un horodatage ISO-8601 en UTC du moment où l'événement a été préparé.
• Un identifiant pour l'objet WordPress associé (ID du lead pour new_lead, ID de la publication et ID de l'annonce pour new_import).
• Un objet data avec un petit ensemble de champs de résumé sur l'événement (champs de base du lead pour new_lead ; champs de base du véhicule pour new_import).

Les récepteurs doivent traiter les champs inconnus comme des ajouts rétrocompatibles et les ignorer plutôt que de rejeter la charge utile. Vérifiez l'ensemble de champs actuel par rapport au document de référence avant de publier votre intégration.

Validation des requêtes entrantes

Lorsqu'un secret de webhook est configuré, le récepteur doit toujours vérifier la signature avant de faire confiance à la charge utile. La règle de vérification est la suivante :

1. Lisez le corps brut de la requête avant toute analyse JSON (l'analyse et la re-sérialisation peuvent modifier l'ordre des octets ou les espaces et casser la signature).
2. Calculez HMAC-SHA256(raw_body, shared_secret) et encodez le résultat sous forme de chaîne hexadécimale en minuscules.
3. Comparez-le à la valeur de l'en-tête X-AS24CI-Signature en utilisant une comparaison en temps constant (la plupart des langages fournissent cela via hash_equals, crypto.timingSafeEqual, hmac.compare_digest ou similaire).
4. Rejetez la requête avec 401 si la signature est manquante ou ne correspond pas.

Contrôles défensifs supplémentaires que le récepteur devrait envisager :

• Rejeter HTTP. N'acceptez que les requêtes HTTPS sur le récepteur.
• Autoriser l'adresse IP source du site WordPress au niveau du réseau ou de la couche applicative, en plus de la vérification de la signature.
• Idempotence. Le même événement logique peut être livré plus d'une fois (voir Comportement de livraison ci-dessous). Utilisez l'ID du lead, l'ID de la publication, l'ID de l'annonce ou un hachage de la charge utile pour dédoublonner du côté du récepteur.
• Fenêtre d'horodatage. Rejetez les requêtes dont le timestamp est trop éloigné dans le passé ou le futur pour limiter la valeur des charges utiles rejouées. Un décalage d'horloge de quelques minutes de chaque côté est normal.
• Tolérance du schéma. Traitez les champs supplémentaires comme rétrocompatibles et les noms d'événements inconnus comme des éléments à journaliser plutôt que de provoquer un plantage.
• Limite de taille du corps. Limitez la taille maximale du corps au niveau du récepteur pour vous protéger contre les entrées malformées.

Si aucun secret n'est configuré, le récepteur n'a aucun moyen de vérifier que la requête provient réellement de l'extension ; configurez un secret à moins que le chemin réseau ne soit entièrement privé et fiable.

Comportement de livraison

L'implémentation actuelle présente les caractéristiques de livraison suivantes. Vérifiez ces comportements dans la version actuelle de l'extension avant de vous y fier.

• La première tentative est de type "tirer et oublier" (fire-and-forget). Lorsqu'un événement est déclenché, l'extension envoie la première livraison sous forme de requête HTTP POST non bloquante. Elle n'attend pas la réponse du récepteur et n'interprète pas le code de réponse lors de cette tentative.
• Tentatives de réessai planifiées. Peu de temps après la première tentative, une livraison de suivi est planifiée via la file d'attente des tâches de WordPress. Si cette livraison renvoie une réponse 5xx ou une erreur de connexion, l'extension planifie d'autres tentatives avec un court délai croissant entre elles.
• Limite de tentatives. L'extension ne réessaie pas indéfiniment. Après un petit nombre de tentatives infructueuses, l'événement est abandonné silencieusement et n'est pas livré plus tard.
• Indépendance par événement. Un échec de livraison pour un événement n'affecte pas l'événement suivant.
• L'ordre n'est pas garanti. Deux événements déclenchés à intervalles rapprochés peuvent arriver dans n'importe quel ordre. Les récepteurs doivent s'appuyer sur les identifiants et les horodatages de la charge utile, et non sur l'ordre d'arrivée.
• Modèle à récepteur unique. Chaque événement a exactement une URL configurée. Pour diffuser vers plusieurs systèmes, configurez un petit redirecteur (par exemple, une plateforme d'automatisation comme Zapier, Make, n8n ou un relais auto-hébergé) comme récepteur et laissez-le distribuer aux systèmes en aval.
• Dépendance à Cron pour les réessais. Les réessais sont planifiés via la file d'attente des tâches de WordPress. Sur les installations qui utilisent le mode Cron du serveur (voir Configuration du Cron du serveur), assurez-vous que la tâche complémentaire qui appelle wp-cron.php est en place — sinon les réessais planifiés ne s'exécuteront pas.

Notes opérationnelles

• Journalisation du côté de WordPress. L'extension journalise l'activité de l'API et de l'importation dans wp-content/uploads/as24ci-logs/. La livraison des webhooks fait partie du fonctionnement normal et peut ne pas générer de journaux détaillés par défaut. L'endroit le plus fiable pour voir ce qui a été livré est le propre journal du récepteur.
• Journalisation du côté du récepteur. Journalisez chaque requête reçue, y compris les en-têtes (avec la signature) et le corps brut, avant tout traitement. Cela facilite grandement la réponse aux incidents et le débogage. Appliquez les règles normales de protection des données du récepteur — les leads contiennent des données personnelles.
• Données personnelles. L'événement new_lead contient des données personnelles soumises par le visiteur (telles que le nom, l'adresse e-mail, le téléphone, le message). Traitez le récepteur comme un sous-traitant de données pour ces informations et appliquez vos règles de confidentialité habituelles. Voir Lead Data and Consent et GDPR / DSGVO Notes.
• Rotation du secret. Lorsque vous modifiez le secret du webhook dans l'extension, mettez à jour le récepteur en même temps. Tant que les deux parties ne sont pas d'accord, chaque livraison sera rejetée par la vérification de la signature.
• Modification de l'URL. La mise à jour de l'URL prend effet pour l'événement suivant. Il n'existe aucun mécanisme intégré pour relivrer les événements historiques.
• Désactivation d'un webhook. Effacez le champ URL et enregistrez. Plus aucun événement de ce type ne sera envoyé.

Limites

• Seuls les deux événements décrits ci-dessus sont émis. Il n'y a pas d'événement intégré pour la suppression de véhicule, le changement de statut de lead, l'abonnement aux alertes de recherche, la réservation d'essai routier ou d'autres actions de l'extension.
• Il n'y a pas d'interface d'administration pour inspecter les tentatives de livraison individuelles ou pour rejouer les événements historiques.
• Il n'y a pas de diffusion native vers plusieurs récepteurs par événement.
• Il n'y a pas de point de terminaison de webhook entrant — l'extension envoie uniquement des webhooks ; elle n'accepte pas de webhooks entrants arbitraires.
• Le nombre de tentatives et les délais peuvent changer d'une version à l'autre de l'extension. Vérifiez le comportement actuel par rapport à Webhook Event Reference avant de publier de la documentation destinée aux clients.

---

Dépannage

Documents connexes

• Référence des événements de webhook
• Webhooks (notes techniques)
• Clés d'option et stockage des réglages
• Données de leads et consentement
• Notes sur le RGPD / DSGVO
• Configuration du Cron du serveur
• Identifiants API externes
• Configuration requise pour l'API, le réseau et le SSL
• Erreurs d'e-mail et de leads