HubSpot API : consentements, opt-in et source de vérité CRM

Le vrai enjeu n’est pas d’afficher une case cochée dans HubSpot. Il faut pouvoir dire quelle personne a accepté quelle finalité, par quel canal, à quel moment, à partir de quelle information et comment elle a ensuite retiré ou modifié son choix. Un booléen sans contexte ne répond à aucune de ces questions.

L’intégration doit aussi distinguer préférences de communication, preuve de collecte et base juridique retenue pour le traitement. Le responsable de traitement reste chargé de déterminer le cadre applicable avec ses conseils ; le connecteur, lui, doit préserver la décision, sa portée et sa chronologie sans en inventer une nouvelle.

Contre-intuitivement, répliquer tous les statuts dans tous les outils ne renforce pas la conformité. Plus il existe de copies capables d’écrire, plus un retrait risque d’être écrasé par un import ancien. Une architecture sûre limite les autorités d’écriture et propage en priorité les choix les plus restrictifs.

Dawap met en œuvre des flux d’intégration API qui relient HubSpot, formulaires, centre de préférences et outils d’envoi avec des contrats versionnés, une piste d’audit et des reprises sans réabonnement silencieux.

Pourquoi un consentement n’est pas une simple case

Le choix est spécifique à une finalité. Une personne peut vouloir recevoir une lettre d’information produit sans accepter des offres de partenaires, ou accepter l’e-mail sans accepter le SMS. Une seule propriété « opt-in » écrase cette granularité et rend les changements impossibles à expliquer.

La nature du message compte également. Prospection commerciale, communication transactionnelle et suivi relationnel ne se traitent pas comme un bloc homogène. La CNIL distingue ces catégories et rappelle que les règles varient selon la nature de la communication, la personne visée et la situation.

Ne pas confondre client, compte créé et permission

La création d’un compte e-commerce ne constitue pas à elle seule une commande ni une autorisation générale de prospection. Le flux ne doit donc pas transformer automatiquement le statut « compte actif » ou « client ERP » en préférence marketing positive.

Les éventuelles exceptions et bases juridiques doivent être documentées par le responsable de traitement pour le cas précis. L’intégration transporte le résultat de cette qualification ; elle ne déduit pas une permission depuis le chiffre d’affaires ou le lifecycle CRM.

Lister les sources qui modifient une préférence

Les changements peuvent venir d’un formulaire HubSpot, d’une page de désinscription, d’un centre de préférences, d’un import, d’un outil événementiel, du support ou d’une autre plateforme d’envoi. L’inventaire doit distinguer les sources de collecte, les systèmes qui exécutent les campagnes et les copies de consultation.

Pour chaque source, la matrice précise les finalités couvertes, les preuves disponibles, le sens de synchronisation, le délai de propagation et l’owner. Une case ancienne dans un back-office ne doit pas posséder le même pouvoir qu’un retrait horodaté reçu depuis le lien du message.

Repérer les écritures cachées

Un import de contacts, une fusion de fiches ou une restauration de base peuvent modifier une préférence sans passer par le parcours normal. Les workflows HubSpot peuvent également recopier une propriété vers une autre. Ces chemins doivent figurer dans la cartographie.

Le test consiste à partir d’un contact désabonné, puis à exécuter chaque import et chaque synchronisation. Si l’un d’eux le réactive sans nouvelle preuve, il constitue une autorité d’écriture cachée qu’il faut retirer ou encadrer.

Séparer finalités, canaux et statuts

Le modèle minimal combine personne, finalité, canal, marque ou entité émettrice, statut, date d’effet et source. Cette clé évite qu’une désinscription à une lettre mensuelle supprime une communication nécessaire au service, ou qu’un accord e-mail ouvre automatiquement le SMS.

Dans HubSpot, les types d’abonnement représentent les catégories de communication. L’API officielle de préférences permet de lire leurs définitions et de gérer un statut par contact et par type. Le mapping doit utiliser les identifiants internes, pas les seuls libellés visibles susceptibles d’évoluer.

Modéliser explicitement l’état indéterminé

« Non renseigné » n’est ni un oui ni un non. Le transformer en opt-in lors d’une migration constitue une décision que les données ne justifient pas. Le contrat garde cet état et applique la règle d’envoi décidée pour le contexte.

Les transitions autorisées sont limitées : une nouvelle collecte prouvée peut ouvrir une finalité ; un retrait la ferme immédiatement ; une correction technique restaure seulement une valeur dont la preuve existe déjà. Chaque transition possède un événement source.

Conserver une preuve proportionnée

La preuve doit permettre de démontrer les conditions du choix : date, point de collecte, texte ou version de l’information, action positive lorsque requise, finalité et identité technique du contact. La CNIL rappelle que le responsable doit pouvoir démontrer le consentement et que le retrait doit rester possible à tout moment.

HubSpot n’a pas besoin de stocker le document complet si un registre dédié le fait mieux. Le CRM peut conserver un identifiant de preuve, le statut courant et la date ; le registre garde le détail immuable et les éléments nécessaires à l’audit.

Minimiser sans rendre la preuve introuvable

Conserver chaque page HTML, adresse IP et payload brut indéfiniment n’est pas une stratégie par défaut. La politique de preuve doit être proportionnée, sécurisée et alignée avec les durées définies par l’organisation.

Le correlation ID relie la préférence HubSpot au dossier de preuve. Une personne habilitée peut retrouver le contexte sans exposer ces détails à tous les utilisateurs du CRM. Les accès et consultations sensibles sont eux-mêmes journalisés.

Définir la priorité entre systèmes

La source de vérité n’est pas forcément un outil unique. Le formulaire peut créer la preuve, le registre la conserver, HubSpot exécuter la segmentation et la plateforme d’envoi appliquer la suppression. La priorité se définit par opération et par finalité.

La règle conservatrice place le retrait au-dessus d’un accord plus ancien. En revanche, deux accords contradictoires ne se départagent pas simplement par la dernière date si l’un ne possède aucune preuve ou porte sur une autre finalité.

Construire une résolution déterministe

Le moteur compare l’identité, la finalité, le canal, l’horodatage, l’autorité de la source et la présence de preuve. Il produit un statut courant, mais conserve tous les événements d’origine. La règle est testée comme du code métier.

Par exemple, si un retrait e-mail daté de 10 h arrive avant un import d’opt-in collecté la veille, alors le retrait reste actif et l’import est classé comme événement obsolète. Aucun workflow ne doit transformer cet écart en réinscription.

Traiter retraits et réactivations

Le retrait doit être propagé rapidement vers tous les outils d’envoi concernés. Un incident de synchronisation ne doit pas autoriser une campagne à partir d’une copie ancienne. Les listes d’exclusion locales constituent un garde-fou temporaire, pas la solution finale.

La réactivation suit un chemin distinct. Elle exige un nouvel événement valide pour la finalité, et non la suppression d’une ligne de désinscription. L’historique conserve le retrait précédent et la nouvelle collecte.

Rendre le retrait au moins aussi simple que la collecte

Un lien de désinscription, un centre de préférences ou une demande support doivent aboutir au même résultat sans parcours dissuasif. La facilité de retrait fait partie du contrôle fonctionnel, au-delà de la simple disponibilité d’un endpoint.

Le scénario de test retire une préférence pendant qu’une campagne est en préparation. Il vérifie le délai d’exclusion dans HubSpot et dans l’outil d’envoi, puis confirme qu’un retry ou un import nocturne ne rétablit pas le statut.

Protéger listes, workflows et campagnes

Les workflows doivent lire le statut effectif de la finalité au moment de l’action, pas seulement lors de l’entrée dans une liste. Une personne peut se retirer entre la segmentation et l’envoi. La dernière vérification doit donc être proche du canal d’exécution.

Une migration de types d’abonnement se prépare comme un changement de contrat. L’équipe cartographie anciens et nouveaux identifiants, simule les populations, vérifie les exclusions et conserve un rollback qui ne réabonne personne.

Bloquer une campagne sur des seuils explicites

Si plus de 0,5 % d’un segment possède un statut divergent entre HubSpot et le registre, alors l’envoi est gelé pour cette population. Le seuil ne transforme pas les autres cas en permissions ; il déclenche une réconciliation avant décision.

Le contrôle affiche le nombre de contacts, les finalités touchées, l’âge du plus ancien retrait non propagé et la cause. Le marketing peut ainsi retirer le sous-ensemble à risque sans perdre toute la campagne.

Journaliser les changements sensibles

L’audit trail enregistre l’event ID, la personne, la finalité, l’ancien et le nouvel état, la source, la date d’effet, la date de traitement et l’identifiant de preuve. Il distingue l’événement métier de ses tentatives techniques.

Un webhook peut être reçu deux fois ou après un batch. L’idempotence repose sur l’événement ou sur une clé déterministe ; l’ordre est résolu avec la date d’effet et la version, pas avec l’heure d’arrivée dans la queue.

Expliquer chaque replay

Le runbook nomme les entrées, la sortie attendue, les responsabilités, le seuil de retry et le repli. Un replay relit l’état cible, vérifie que l’événement n’est pas obsolète, puis applique ou classe la transition.

Après un timeout, le flux consulte les préférences via l’API HubSpot avant d’écrire de nouveau. Si l’état attendu est déjà présent, il rattache la preuve et clôt la tentative au lieu de produire une seconde transition.

Gouverner le flux en production

Le tableau de bord suit retraits en attente, divergences par finalité, événements sans preuve, réactivations, erreurs API et âge des files. Le volume d’opt-in n’est pas un indicateur de qualité ; il peut même signaler une réinscription accidentelle.

Le marketing possède les usages de campagne, l’équipe CRM les types d’abonnement, le juridique ou DPO le cadre interne, le support les demandes reçues et l’intégration la propagation. Les arbitrages sont consignés dans un contrat commun.

Auditer les autorités d’écriture

Une revue périodique inventorie les tokens OAuth, scopes, imports, workflows et comptes capables de modifier les préférences. Tout accès sans owner ou sans usage actif est retiré. Les permissions d’écriture sont plus rares que celles de lecture.

Le monitoring alerte sur une hausse anormale de réactivations ou de changements en masse. Un batch légitime porte un change record et un périmètre attendu ; une variation sans contexte déclenche le gel de la synchronisation.

Pour qui cadrer les préférences HubSpot

Ce cadrage concerne les organisations qui collectent ou exécutent des préférences dans plusieurs outils : site, application, HubSpot, plateforme événementielle, centre de préférences ou autre solution d’envoi. Il devient prioritaire dès qu’une désinscription met plusieurs heures à se propager ou qu’une fusion de contact peut modifier le statut.

Faire décider marketing, CRM, support et juridique

Le marketing définit les usages et catégories de communication. L’administration CRM traduit ces catégories en types d’abonnement. Le support traite les demandes. Le DPO ou conseil compétent qualifie le cadre. L’intégration garantit que la décision circule sans être élargie.

Les termes doivent être partagés : finalité, canal, preuve, retrait, opposition, statut non renseigné et communication transactionnelle. Une propriété technique ne doit pas cacher plusieurs décisions réglementaires différentes.

Différer si les finalités ne sont pas nommées

Il faut différer la synchronisation bidirectionnelle lorsqu’un unique champ mélange newsletter, offres partenaires et SMS, ou quand les sources anciennes n’ont aucune preuve. Migrer ce flou vers HubSpot ne le rend pas plus fiable.

Le pilote peut commencer par une finalité, une marque et un canal dont le parcours est maîtrisé. Les états inconnus restent exclus de l’envoi jusqu’à une décision documentée, sans être convertis artificiellement.

Plan d’action par finalité

Jours 1 à 10 : inventaire et contrat de décision

Choisir une finalité e-mail et cartographier tous ses points de collecte, de retrait et d’envoi. Exporter les types d’abonnement HubSpot, les propriétés voisines, les workflows et les listes. Pour chaque source, documenter identité, statut, preuve, horodatage, autorité et délai de propagation.

Écrire les transitions et leur priorité : collecte valide, retrait, statut inconnu, import ancien, fusion et réactivation. Préparer des jeux de tests avec choix partiel, double événement, webhook en retard et contact fusionné. Le résultat attendu est validé par les responsables métier compétents.

Jours 11 à 30 : pilote et réconciliation

Activer une population bornée avec queue, idempotence, instrumentation et journalisation. Le monitoring compare le registre, HubSpot et l’outil d’envoi. Le rollback ferme l’envoi ou restaure une exclusion ; il ne recrée jamais un accord absent.

Après deux cycles de campagne, mesurer le délai de retrait, les divergences, les événements obsolètes et les corrections manuelles. Le bilan sépare les défauts de collecte, de transport et d’exécution afin d’attribuer chaque correction à la bonne équipe. Une personne extérieure à l’équipe projet exécute le runbook sur un incident simulé avant l’extension à une autre finalité.

• Définir une clé distincte par personne, finalité, canal et marque.
• Inventorier toutes les opérations capables d’écrire une préférence.
• Préserver la date d’effet et la preuve lors d’une reprise.
• Tester le retrait pendant une campagne et après une fusion de contacts.
• Étendre seulement lorsque le statut inconnu reste explicitement traité.

Erreurs fréquentes sur l’opt-in

Les défauts les plus risqués simplifient trop la donnée : un booléen universel, une règle « dernière écriture gagnante », une fusion qui conserve l’opt-in le plus favorable ou un import qui transforme les valeurs vides en accord.

Réabonner après une mise à jour de profil

Une correction d’e-mail ou de nom ne constitue pas un nouveau choix. Le flux doit préserver les préférences lors du changement d’identité et rattacher l’historique à la personne selon la procédure définie.

Si l’identité reste ambiguë, la règle la plus prudente s’applique au canal concerné jusqu’à résolution. Le coût commercial d’une exclusion temporaire est visible ; celui d’un message envoyé après retrait est souvent découvert trop tard.

Confondre absence de retrait et accord

Une base ancienne peut ne contenir aucune désinscription parce qu’elle n’enregistrait pas l’information. Elle ne prouve pas pour autant une préférence positive. L’état est importé comme inconnu et traité selon la règle validée.

Le coût caché apparaît dans les plaintes, la réputation d’envoi, le support et l’enquête nécessaire pour reconstruire une preuve. La qualité du flux se mesure d’abord à sa capacité de respecter et d’expliquer les refus.

• Ne pas utiliser la date d’import comme date de collecte.
• Ne pas fusionner deux finalités sous un même type d’abonnement.
• Ne pas laisser un CRM secondaire réactiver une préférence retirée.
• Ne pas rejouer un événement sans vérifier son ancienneté et l’état cible.

Sources et lectures complémentaires

Les règles doivent être validées pour le contexte réel. Les sources officielles apportent le cadre ; la documentation HubSpot précise les capacités techniques ; le contrat interne relie les deux sans transformer le connecteur en conseil juridique.

La page intégrateur HubSpot API permet ensuite de cadrer l’inventaire, le mapping et le pilote.

Vérifier cadre, API et modèle de données

La CNIL rappelle notamment les critères d’un consentement valable, la preuve et la possibilité de retrait. HubSpot documente son API v4 de préférences de communication, les types d’abonnement et les statuts par contact.

• CNIL : prospection commerciale par voie électronique
• HubSpot : API des préférences de communication
• HubSpot : relier leads e-commerce, clients et ERP
• Contrats de données : conserver sens, version et responsabilité

Conclusion : faire du retrait la règle la mieux protégée

Un flux de préférences fiable ne cherche pas à maximiser les opt-in. Il conserve une décision spécifique, sa preuve et son retrait, puis garantit que chaque outil d’envoi applique l’état courant sans élargir sa portée.

La source de vérité se définit par opération : collecte, preuve, exécution et consultation peuvent vivre dans des systèmes différents. Ce qui compte est une résolution déterministe et une chronologie que l’équipe peut relire.

Commencer par une finalité et un canal permet de tester les imports, fusions, retards et retries avant d’étendre. Le succès se voit lorsqu’un retrait traverse la chaîne plus sûrement qu’un accord ancien.

Dawap accompagne cette mise sous contrôle via son offre d’intégration API : cartographie des autorités, contrat de préférences, audit trail, tests d’échec et déploiement progressif avec les équipes CRM et métier.