Référence des événements de webhook

Cette annexe décrit les événements de webhook sortants déclenchés par l'extension ADP Car Market Hub.

Quand utiliser ce document

Utilisez cette référence lors de la création d'un récepteur, de la vérification des signatures ou de la documentation d'une intégration. Pour la description conceptuelle, voir Webhooks.

Aperçu

L'extension peut déclencher deux événements de webhook sortants :

• new_lead — lorsqu'une soumission de formulaire de contact est enregistrée en tant que lead.
• new_import — lorsqu'un véhicule est créé ou mis à jour lors d'une importation.

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

Les événements sont indépendants : la configuration d'une URL n'active pas l'autre. Laisser une URL vide désactive entièrement cet événement.

Note sur le comportement actuel : Dans la version actuelle de l'extension, seul new_import est réellement distribué. Le chemin de distribution de new_lead est présent (le récepteur, la signature et l'option as24ci_webhook_url_new_lead existent tous) mais son déclencheur n'est pas activé dans le code actuel, donc configurer une URL new_lead ne produira pas encore de requêtes. Pour les notifications de leads aujourd'hui, fiez-vous aux e-mails de leads (voir Référence des leads). Le schéma ci-dessous documente la charge utile new_lead prévue pour les récepteurs qui souhaitent s'y préparer.

Résumé des événements

Un secret de signature partagé est configuré globalement via as24ci_webhook_secret.

Format de la charge utile

Toutes les charges utiles sont des objets JSON avec event, timestamp (ISO 8601, UTC) et un bloc de données spécifique à l'événement.

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

La charge utile new_import est déclenchée à la fois pour les nouvelles insertions et les mises à jour. Le rappel du hook reçoit un drapeau is_update en interne ; la charge utile sortante elle-même n'inclut pas ce drapeau dans la version actuelle de l'extension. Vérifiez si votre intégration nécessite de distinguer les deux cas par rapport au code source actuel avant de publier.

Vérification de la signature

Lorsque as24ci_webhook_secret est défini, l'extension 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 le résultat 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.

Distribution, 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 »). L'extension 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é.
• En cas d'erreurs de connexion ou de 5xx HTTP, l'extension 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 de nouvelles tentatives ; 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 les tâches lourdes de manière asynchrone.

Configuration

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.

Notes opérationnelles

• L'extension déclenche uniquement des webhooks ; elle ne maintient pas de file d'attente de distribution, de journal de relecture ou de stockage des messages non distribués. Si une distribution fiable et ordonnée est essentielle pour votre cas d'utilisation, placez le récepteur derrière une couche de file d'attente.
• 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 côté utilisateur car la première tentative est non bloquante.
• La charge utile new_lead comprend uniquement le petit ensemble de champs présenté ci-dessus. Des métadonnées de lead supplémentaires sont disponibles en interrogeant le type de publication as24ci_lead avec les fonctions WordPress habituelles.
• La charge utile new_import reste volontairement 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 qu'elle est validée en tant qu'URL. Vérifiez les journaux de l'extension et le journal d'erreurs du serveur web.
• Le webhook arrive une fois mais pas de tentative de relecture. La première tentative est volontairement de type « fire-and-forget » ; 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.
• Distributions de new_import en double. La détection des modifications ignore les véhicules dont la charge utile est inchangée, mais une synchronisation complète forcée peut réémettre des événements pour des annonces déjà connues.
• 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 vraie tâche cron ou le point de terminaison cron REST décrit dans la Référence des hooks de cron.

Documents connexes

• Webhooks
• Intégration des webhooks
• Référence des points de terminaison REST
• Référence des hooks de cron
• Référence des réglages