Introduction

Avant de commencer

Adlead peut envoyer des webhooks pour notifier votre application chaque fois qu'un événement se produit. Cela est particulièrement utile pour les événements tels que la création d'un nouveau lead et la mise à jour de certains statuts.

Ce mécanisme est également utile pour les services qui ne sont pas directement responsables de la création d'une requête API, mais qui ont néanmoins besoin de connaître la réponse de cette requête.

Note de version

Dernière mise à jour le 22/07/2025

Format des requêtes

Tous les appels sont de type POST et réalisés avec les headers HTTP suivants :

Nom du header	Valeur
signature	Signature HMAC de la requête
Content-Type	application/json

Authentification des requêtes

Afin de vous permettre d'authentifier les webhooks en provenance d'Adlead, chaque requête réalisée est signée, cette signature est disponible dans le header, dans l'attribut signature.

Pour vérifier la requête, il faut utiliser votre clé d'accès accessKey fournie lors de l'ouverture de votre accès.

<?php
// Payload envoyé par la requête (contenu du body)
$payload = '{"event":"option:deleted","data":{"id":2566,"context":{"tenant_key": "espace-client","program_id": 74}}}';

// Clé d'accès 'accessKey' alphanumérique de 24 caractères fournie lors de l'ouverture de votre accès ex : 420e21f80c946a0012f6acfe
$secret  = 'ma-clé';

// Signature fournie dans le header de la requête
$headerSignature = 'd5cc11bca0cdbbfc4c1faef5f575c35fe6d5c2b4bb96920425a28f3fe49b0673';

$hash = hash_hmac('sha256', $payload, $secret);
if ($hash === $headerSignature) {
    echo 'La requête est vérifiée !';
}

const crypto = require('crypto');

// Payload envoyé par la requête (contenu du body)
// Merci de noter qu'il est nécessaire d'utiliser le payload raw, certains parsers peuvent introduire de légères différences dans le payload.
const payload = '{"event":"option:deleted","data":{"id":2566,"context":{"tenant_key": "espace-client","program_id": 74}}}';

// Clé d'accès 'accessKey' alphanumérique de 24 caractères fournie lors de l'ouverture de votre accès ex : 420e21f80c946a0012f6acfe
const secret = 'ma-clé'; 

// Signature fournie dans le header de la requête
const headerSignature = 'd5cc11bca0cdbbfc4c1faef5f575c35fe6d5c2b4bb96920425a28f3fe49b0673';

const hash = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (hash === headerSignature) {
  console.log('La requête est vérifiée !');
}

Gestion des erreurs

L'envoi des webhooks peut échouer pour différentes raisons, telles que les suivantes :

• Délais d'attente : nous n'avons pas reçu de réponse 2xx dans un délai de 15 secondes après l'envoi du webhook.
• Accès non autorisé : une autorisation du serveur est requise, mais une authentification non valide a été fournie.
• La requête a été redirigée : nous ne suivons pas les redirections HTTP, et nous les traitons donc comme des échecs de webhook.
• Le SSL configuré sur le serveur distant n'est pas valide.

Si un webhook échoue, nous tenterons de l'envoyer à nouveau jusqu'à 3 fois à des intervalles exponentiels :

• 1er renvoi : 10 secondes
• 2ème renvoi : 100 secondes (~ 1.5 minutes)
• 3ème renvoi : 1000 secondes (~ 16 minutes)

Désactivation en cas d'erreurs

IMPORTANT

En cas d'erreurs à répétition sur les URLs fournies, les webhooks seront automatiquement désactivés.

Gestion de l'ordre des événements

Dans le cadre d'une architecture asynchrone, l'ordre de réception des webhooks ne peut pas être garanti. Il est en effet possible que plusieurs événements déclenchés dans un ordre précis côté Adlead arrivent dans un ordre différent côté récepteur.

Cela peut notamment s'expliquer par les causes suivantes :

• Latence réseau variable entre les envois.
• Temps de traitement applicatif différents selon les événements.
• Retry mechanism en cas d'échec temporaire, pouvant faire arriver un événement plus ancien après un plus récent.
• Exécution parallèle via des workers ou des files d'attente multiples.

Pour vous permettre de reconstituer l'ordre logique des événements, chaque webhook envoyé par Adlead contient un champ emitted_at à la racine du payload.

Ce champ indique la date et l'heure exacte d'émission de l'événement, au format ISO 8601 (ex : 2024-09-04T10:20:04.000000Z).

Vous pouvez vous appuyer sur cette information pour :

• Contrôler la cohérence temporelle des événements reçus.
• Reclasser les événements dans leur ordre réel d'émission, si l'ordre d'arrivée ne correspond pas à l'ordre logique attendu.
• Éviter les erreurs de traitement liées à une réception désordonnée.

Il est recommandé d'utiliser ce champ dans vos processus d'intégration afin de renforcer la fiabilité globale du traitement des webhooks.

Limites inhérentes aux webhooks

Bien que les webhooks soient un mécanisme efficace pour être tenu informé des événements en temps réel, ils présentent certaines limites structurelles qu'il convient de prendre en compte :

• Asynchronisme : Les webhooks fonctionnent de manière asynchrone. L'ordre de réception des événements n'est pas garanti, notamment en cas de latence réseau variable, de traitements parallèles ou de mécanismes de retry.
• Pas de garantie absolue de réception : Même si nous mettons en oeuvre jusqu'à trois tentatives en cas d'échec, certains types d'erreurs (SSL non valide, redirection HTTP, timeouts prolongés, etc.) peuvent empêcher la bonne réception d'un événement.
• Pas de vision d'état global : Les webhooks représentent un flux d'événements incrémentaux. Ils ne permettent pas à eux seuls de reconstituer l'état complet d'un objet à un instant T. Il est donc nécessaire de maintenir une logique d'agrégation et de persistance côté récepteur.
• Risque de désynchronisation : Compte tenu du volume important d'événements transmis par Adlead à l'ensemble de ses partenaires, il est possible que certains cas limites surviennent (par exemple, un événement manquant ou arrivé dans un ordre inattendu).

REMARQUE

Pour renforcer la fiabilité de votre intégration, il est donc recommandé de compléter l'usage des webhooks par des contrôles de cohérence réguliers afin de détecter et corriger d'éventuelles divergences entre les systèmes.