Guide · HubSpot
Webhook HubSpot : chaque conversion attribuée
HubSpot sait quelle affaire a été gagnée, et pour combien. Il ne sait pas quelle campagne l'a fait entrer. Un workflow, un en-tête d'autorisation, et les deux moitiés de l'histoire se rejoignent.
Ce que HubSpot envoie, ce que Subtraq répond
201
POST /api/v1/sales — Authorization: Bearer stq_sk_… { "space": "boulangerie-martin", "amount": 430000, "currency": "EUR", "invoiceId": "deal-18452119", "email": "[email protected]" } → 201 Created { "ok": true, "attributed": true, "duplicate": false, "eventId": "…" }
Le montant est en centimes : 4 300 € s'écrit 430000. Subtraq ne met jamais un nombre à virgule sur de l'argent. Et attributed dit la vérité : true quand la vente a retrouvé son lien, false quand elle n'en a pas trouvé — jamais une origine inventée.
À vérifier avant de commencer
L'action webhook n'existe pas sur toutes les formules
Si votre portail n'y a pas droit, rien n'est perdu : un workflow peut prévenir Zapier, Make ou n8n, et c'est l'intermédiaire qui pose l'en-tête d'autorisation. Un maillon de plus, donc un endroit de plus où ça peut casser, mais le résultat est le même.
Vérifiez-le maintenant plutôt qu'au sixième réglage. Une formule qui ne porte pas l'action ne l'affiche pas : on croit alors avoir mal cherché.
Source : les webhooks dans les workflows HubSpot.
Où vit « Send a webhook »
D'après la base de connaissances HubSpot, l'action Send a webhook des workflows est disponible sur Data Hub Professional et Enterprise — l'offre anciennement nommée Operations Hub. Elle apparaît dans la section « Data ops » de l'éditeur.
Dans HubSpot, 7 étapes
De l'étape « Closed won » à la vente attribuée
Rien à installer, rien à publier. Un workflow, une action, un en-tête : HubSpot sait poser lui-même l'autorisation que Subtraq exige.
Dans Subtraq, créez une clé serveur
Installation → Clés d'API. Elle commence par stq_sk_, porte le droit events:write, et ne s'affiche qu'une fois. Relevez aussi le slug de l'espace client, lisible dans l'adresse de son tableau de bord.
Dans HubSpot, créez un workflow basé sur les affaires
Le déclencheur se règle sur la propriété « Deal stage » et la valeur « Closed won ». L'identifiant interne de cette étape dépend du portail : HubSpot l'expose par son API des pipelines si vous voulez le lire.
Ajoutez l'action « Send a webhook »
Elle se trouve dans la section « Data ops » de l'éditeur de workflow. Méthode POST, URL https://subtraq.co/api/v1/sales.
Réglez l'authentification sur « API key »
La section Authentication de l'action demande un nom de clé et une valeur, placés en en-tête de requête. Nom : Authorization. Valeur : Bearer suivi de la clé serveur. C'est ce réglage qui remplace, chez HubSpot, l'en-tête que la plupart des outils ne savent pas poser.
Choisissez « Customize request body »
Par défaut HubSpot envoie toutes les propriétés de l'affaire, ce que Subtraq refusera. Composez le corps champ par champ : space, amount, currency, invoiceId, email. Le montant de l'affaire s'écrit en unité principale côté HubSpot : il doit arriver en centimes.
Mettez l'identifiant de l'enregistrement dans invoiceId
La propriété hs_object_id — le « Record ID » de l'affaire — est stable et unique. C'est la clé d'idempotence idéale : une affaire repassée en gagné après un aller-retour ne compte pas deux fois.
Faites passer une affaire de test en gagné
L'historique du workflow montre la réponse. Subtraq répond 201 pour une vente nouvelle, 200 pour un doublon, et dit dans les deux cas si la vente a retrouvé son lien d'origine.
Chemins relevés dans la base de connaissances HubSpot le 12 septembre 2026 — l'action webhook et les propriétés d'affaire par défaut. Une interface change : si ce que vous voyez ne correspond plus, la source fait foi.
Le meilleur de ce guide
Retrouver le lien d'origine d'un contact, dès le formulaire
Créez donc une propriété de contact au nom interne st_id, posez-la en champ caché sur le formulaire : elle se remplit d'elle-même quand le visiteur arrive par un lien suivi. Envoyez-la ensuite dans le champ clickId de la requête, à la place de l'email ou en plus de lui.
La différence est réelle. L'email rattache une personne si elle a donné la même adresse des deux côtés et si le clic est encore dans la fenêtre. L'identifiant de clic rattache le clic lui-même, et il n'a pas besoin qu'on devine.
Les deux peuvent voyager ensemble : la route accepte email, externalId et clickId dans la même requête, et il lui suffit d'un seul des trois.
Sources : les champs cachés et le remplissage par paramètre d'URL, relevées le 12 septembre 2026.
Le clic entre par le formulaire
HubSpot documente les champs cachés de formulaire, et le remplissage automatique d'un champ par un paramètre d'URL, qui apparie le nom interne de la propriété au nom du paramètre. Un lien Subtraq transmet à la destination un paramètre nommé st_id.
Les cas pénibles, traités franchement
Un cycle de vente n'est pas une caisse de supermarché. Voici ce que Subtraq fait, et ce qu'il ne fait pas.
L'affaire est gagnée six semaines après le premier clic. Elle est encore attribuée ?
Cela dépend de la fenêtre d'attribution de l'espace client : trente jours par défaut, réglable. Au-delà, la vente est enregistrée mais non attribuée. Sur des cycles longs, allongez la fenêtre avant de brancher : elle ne rattrape pas le passé.
Une affaire repasse de gagné à en cours, puis de nouveau en gagné.
Le workflow se déclenche une seconde fois, mais l'identifiant de l'enregistrement n'a pas changé : le même invoiceId arrive, Subtraq reconnaît le doublon, répond 200 et n'ajoute rien. C'est précisément pour ce cas que le champ existe.
Le montant de l'affaire change après coup.
Il ne sera pas corrigé tout seul, et c'est une limite à connaître : la route écrit une vente, elle ne la modifie pas. Un même identifiant de facture est considéré comme déjà traité. Pour un montant révisé, envoyez une seconde vente avec un identifiant distinct et un eventName qui dit ce qu'elle est.
Et une affaire perdue, ou un remboursement ?
Subtraq n'accepte pas de montant négatif et n'a pas d'appel d'annulation. Une affaire perdue ne s'envoie donc simplement pas ; un remboursement se trace par un événement à zéro et se corrige à la main dans le rapport. Mieux vaut le dire que de laisser croire à une compensation automatique.
Questions fréquentes
Faut-il installer une application HubSpot ?
Non. Aucune application à publier, aucun développement. L'action webhook fait partie de l'éditeur de workflow sur les formules qui y ont droit.
Peut-on déclencher sur un contact plutôt que sur une affaire ?
Oui, et c'est même le bon choix quand ce que vous mesurez est un prospect et non une vente. Le principe ne change pas : une action webhook, un en-tête d'autorisation, un corps composé à la main.
Peut-on envoyer un prospect sans montant ?
La route des ventes attend un montant. Pour un prospect sans chiffre, la voie la plus simple reste le lien Subtraq collé dans le champ de redirection du formulaire : l'envoi du formulaire devient alors une conversion, sans aucun appel d'API.
Où lit-on que la requête est bien partie ?
Dans l'historique du workflow HubSpot, qui conserve la réponse reçue. Et dans Subtraq, où la conversion apparaît avec son lien d'origine, ou sans, si elle n'a pas pu être rattachée.
La clé serveur est-elle visible par le client final ?
Non. Elle vit dans le réglage d'authentification du workflow, côté HubSpot, et ne traverse jamais un navigateur. C'est aussi pourquoi les montants ne passent jamais par le mouchard de page.
Sans Data Hub Professional, passez par un intermédiaire
Un workflow qui prévient Zapier, Make ou n8n, et c'est l'intermédiaire qui pose l'en-tête Authorization. Le résultat dans le rapport est identique.
Le guide ZapierLa prochaine affaire gagnée peut dire d'où elle vient
Créez le compte, prenez une clé serveur, ajoutez l'action au workflow. Le premier « Closed won » fait le reste.
Créer un compte gratuit