Utilisation des webhooks avec les workflows HubSpot

Utilisez les webhooks des workflows pour envoyer ou récupérer des informations entre HubSpot et d'autres outils externes. Les webhooks peuvent être utilisés de diverses manières. Exemples d'utilisation fréquente de webhooks :

• Publication des données d'un contact HubSpot dans un autre système, comme un CRM, lorsque ce contact remplit un formulaire précis de votre site.

• Envoi des données de transaction à un système de gestion des envois externe pour créer un bon de commande.

• Récupération des données d'un autre système pour mettre à jour vos fiches d'informations HubSpot.

Vous pouvez envoyer des demandes POST et GET à l'aide de workflows. HubSpot régule le trafic des webhooks séparément des autres processus de workflow, afin de simplifier le workflow et les performances des webhooks. Lorsqu'un webhook est lent ou expire, l'exécution de l'action du workflow peut prendre plus de temps que prévu.

Remarque : HubSpot réessayera les webhooks ayant échoué pendant trois jours maximum, en commençant une minute après l'échec. Les tentatives après les échecs ultérieurs seront effectuées à intervalles croissants, avec un écart maximum de huit heures entre les tentatives. Les workflows ne seront pas réexécutés après la réception de codes de statut de réponse 4XX.
Les erreurs de limite de débit 429 constituent une exception à cette règle ; les workflows seront à nouveau exécutés automatiquement après avoir reçu une réponse 429 et respecteront l'en-tête Retry-After s'il est présent. Retry-After est enregistré en millisecondes. Découvrez-en davantage sur les exceptions de code d'erreur dans la documentation des développeurs de HubSpot.

Découvrez-en davantage sur les webhooks dans la documentation sur les webhooks pour les développeurs. Si vous avez des questions concernant la mise en œuvre spécifique des webhooks avec HubSpot, contactez les Forums des développeurs de HubSpot.

Configurer une requête POST

1. Depuis votre compte HubSpot, accédez à Automatisation > Workflows.
2. Pour modifier un workflow existant, cliquez sur son nom. Autrement, créez un nouveau workflow .
3. Dans l'éditeur de workflow, cliquez sur l'icône Plus (+) pour ajouter une action.
4. Dans le panneau de gauche, dans la section Opérations de données, sélectionnez Envoyer un webhook.
    

5. Cliquez sur le menu déroulant Méthode et sélectionnez POST.
6. Saisir l'URL du webhook.
   • Les URL de webhook sont soumises à un protocole sécurisé et doivent commencer par HTTPS.
   • Pour demander des informations spécifiques, vous pouvez ajouter des paramètres de demande tels que l'URL du webhook ?queryparameter=abc.
   • Si aucun paramètre de demande n'a été ajouté, une demande POST ou GET générique sera envoyée.
7. Définissez votre type d'authentification pour authentifier les demandes adressées à votre webhook. Vous pouvez utiliser une signature de requête dans l'en-tête de votre webhook ou une clé d'API :
   • Pour utiliser une signature de requête dans l'en-tête de votre webhook :
     • Cliquez sur le menu déroulant Type d'authentification. Puis, sélectionnez Inclure une signature de requête dans l'en-tête.
     • Puis, saisissez votre ID d'application HubSpot. Découvrez comment vérifier les signatures de demande.
   • Pour utiliser une clé d'API ou une application publique créée par le biais d'un compte de développeur pour l'authentification :
     • Lors de l'utilisation d'une clé d'API pour l'authentification, le nom de la clé d'API et son emplacement dépendent de la manière dont le webhook est configuré. Pour des raisons de sécurité, la clé d'API ne sera pas affichée dans les demandes de test. Pour utiliser une clé d'API :
       • Cliquez sur le menu déroulant Type d'authentification. Sélectionnez ensuite la clé d'API.
       • Saisissez le nom de votre clé d'API.
       • Cliquez sur le menu déroulant Emplacement de la clé d'API. Ensuite, sélectionnez Paramètres de demande ou En-tête de demande. Découvrez-en davantage sur l'utilisation des clés d'API dans HubSpot.
     • Si vous faites une demande aux API HubSpot :
       • Cliquez sur le menu déroulant Clé d'API et sélectionnez un secret. La valeur du secret doit être au format Bearer [VOTRE_JETON].
       • Définissez la valeur du nom de la clé d'API sur Autorisation.
       • Définissez la valeur de l'emplacement de la clé d'API sur En-tête de demande.
8. Pour inclure toutes les propriétés, sélectionnez Inclure toutes les propriétés de [objet].
9. Pour inclure uniquement certaines propriétés :
   • Sélectionner Personnaliser le corps de la demande.
   • Pour personnaliser le corps de la demande à l'aide d'une propriété HubSpot, saisissez la clé et sélectionnez une propriété. Pour ajouter une autre propriété, cliquez sur Ajouter une propriété.
   • Pour personnaliser le corps de la demande à l'aide d'un champ statique, saisissez la clé et la valeur. Pour ajouter une autre propriété, cliquez sur Ajouter une valeur statique.
   • Pour supprimer une propriété ou une valeur statique, cliquez sur l'icône Corbeille delete.
10. Cliquez sur Enregistrer.

Remarque : Pour sélectionner plusieurs sorties, la réponse doit être structurée sous la forme d'un objet.

Configurer une requête GET

1. Depuis votre compte HubSpot, accédez à Automatisation > Workflows.
2. Pour modifier un workflow existant, cliquez sur son nom. Autrement, créez un nouveau workflow .
3. Dans l'éditeur de workflow, cliquez sur l'icône Plus (+) pour ajouter une action.
4. Dans le panneau de gauche, dans la section Opérations de données, sélectionnez Envoyer un webhook.
    

5. Cliquez sur le menu déroulant Méthode et sélectionnez GET.
6. Saisir l'URL du webhook.
   • Les URL de webhook sont soumises à un protocole sécurisé et doivent commencer par HTTPS.
   • Pour demander des informations spécifiques, vous pouvez ajouter des paramètres de demande tels que l'URL du webhook ?queryparameter=abc.
   • Si aucun paramètre de demande n'a été ajouté, une demande POST ou GET générique sera envoyée.
7. Définissez votre type d'authentification pour authentifier les demandes adressées à votre webhook. Vous pouvez utiliser une signature de requête dans l'en-tête de votre webhook ou une clé d'API :
   • Pour utiliser une signature de requête dans l'en-tête de votre webhook :
     • Cliquez sur le menu déroulant Type d'authentification. Puis, sélectionnez Inclure une signature de requête dans l'en-tête.
     • Puis, saisissez votre ID d'application HubSpot. Découvrez comment vérifier les signatures de demande.
   • Pour utiliser une clé d'API ou une application publique créée par le biais d'un compte de développeur pour l'authentification :
     • Lors de l'utilisation d'une clé d'API pour l'authentification, le nom de la clé d'API et son emplacement dépendent de la manière dont le webhook est configuré. Pour des raisons de sécurité, la clé d'API ne sera pas affichée dans les demandes de test. Pour utiliser une clé d'API :
       • Cliquez sur le menu déroulant Type d'authentification. Sélectionnez ensuite la clé d'API.
       • Saisissez le nom de votre clé d'API.
       • Cliquez sur le menu déroulant Emplacement de la clé d'API. Ensuite, sélectionnez Paramètres de demande ou En-tête de demande. Découvrez-en davantage sur l'utilisation des clés d'API dans HubSpot.
     • Si vous faites une demande aux API HubSpot :
       • Cliquez sur le menu déroulant Clé d'API et sélectionnez un secret. La valeur du secret doit être au format Bearer [VOTRE_JETON].
       • Définissez la valeur du nom de la clé d'API sur Autorisation.
       • Définissez la valeur de l'emplacement de la clé d'API sur En-tête de demande.
8. Si vous configurez une demande GET, vous pouvez utiliser les propriétés HubSpot ou ajouter des valeurs statiques comme paramètres de demande : 

9. Pour utiliser une propriété HubSpot comme paramètre de demande :
   • Dans la section Paramètres de demande, saisissez la clé, puis sélectionnez une propriété.
   • Pour ajouter une autre propriété, cliquez sur Ajouter une propriété.
   • Pour supprimer une propriété, cliquez sur l'icône Supprimer delete.
10. Pour utiliser une valeur statique comme paramètre de demande :
    • Dans la section Paramètres de requête, saisissez la clé, puis une valeur.
    • Pour ajouter une autre propriété, cliquez sur Ajouter une valeur statique.
    • Pour supprimer une propriété, cliquez sur l'icône Supprimer delete.
11. Cliquez sur Enregistrer.

Définissez une limite de taux pour votre webhook

Définissez une limite de débit pour déterminer la vitesse à laquelle l’action de webhook doit s’exécuter. La limite de débit affectera également toutes les actions suivantes dans le workflow.

1. Depuis votre compte HubSpot, accédez à Automatisation > Workflows.
2. Cliquez sur le nom du workflow.
3. Dans l'éditeur de workflow, cliquez sur l'action Envoyer un webhook.
4. Dans le panneau de gauche, cliquez sur Configurer la limite de débit pour développer la section.
5. Cliquez pour activer l’option Activer la limitation de débit . Par défaut, ce paramètre est désactivé. 
6. Définissez votre limite de débit : 
   • Exécutions d’actions : définissez le nombre maximum d’exécutions par période. 
   • Période : définissez le cadre temporel de votre limite. Vous pouvez définir cette période en secondes, minutes ou heures. 

Tester votre webhook dans HubSpot

Lorsque vous configurez votre webhook POST ou GET, vous pouvez exécuter un test pour visualiser la réponse du webhook. Pendant le test, alors que les données sont envoyées et récupérées par un tiers, les fiches d'informations existantes dans HubSpot ne seront pas affectées. Si vous utilisez une clé d'API pour l'authentification, la clé d'API ne s'affichera pas dans les demandes de test.

Après avoir testé votre webhook, vous pouvez sélectionner les champs de résultat à utiliser comme entrées plus tard dans votre workflow. Sélectionnez uniquement les résultats disponibles dans chaque réponse. Si le résultat est utilisé dans une action ultérieure mais n'est pas disponible dans la réponse, l'action échouera.

1. Depuis votre compte HubSpot, accédez à Automatisation > Workflows.
2. Cliquez sur le nom du workflow.
3. Dans l'éditeur de workflow, cliquez sur l'action Envoyer un webhook.
4. Dans le panneau de gauche, cliquez sur Action de test pour développer la section.
5. Si vous testez une demande POST, la configuration du test de webhook variera selon que vous avez choisi Personnaliser le corps de la demande ou l'action Inclure toutes les propriétés de [objet] dans le webhook.
   • Si vous avez sélectionné Personnaliser le corps de la demande, saisissez les valeurs de test de la propriété pour votre test.
   • Si vous avez sélectionné Inclure toutes les propriétés de [objet], cliquez sur le menu déroulant de [objet], puis sélectionnez une fiche d'informations à tester.
6. Cliquez sur Tester.
7. Pour vérifier les détails du webhook, sélectionnez l'onglet Réponse ou Demande. Dans chaque onglet, vous pouvez cliquer sur Tout ouvrir pour développer toutes les sections ou sur Tout réduire pour réduire toutes les sections.
   • Dans l'onglet Réponse, cliquez sur headers: ou body: pour développer chaque section.
   • Dans l'onglet Demande, cliquez sur httpHeaders: pour développer la section.
     
     

Tester votre webhook en externe

Après avoir créé un workflow avec une action webhook, vous pouvez effectuer un test rapide avec une URL de webhook.

1. Dans votre navigateur, accédez à https://webhook.site et copiez l'URL unique.
2. Dans le champ URL du webhook dans l'action de votre webhook, collez l'URL.
3. Une fois que votre workflow a été activé, vous pouvez inscrire manuellement un contact de test.
   
   

4. Lorsque vous testez votre webhook en externe :
   • Si une action de webhook avec une demande POST est déclenchée, un corps de réponse JSON sera envoyé au webhook contenant toutes les informations sur le contact, y compris les soumissions de formulaires, les abonnements et toutes les valeurs des propriétés de contact. Le système destinataire peut ensuite analyser les données JSON et les utiliser pour sa propre application.
   • Si une action de webhook avec une demande GET est déclenchée, une demande GET générique sera envoyée, sauf si des paramètres de demande supplémentaires ont été appliqués.

Remarque : L'historique des valeurs d'une propriété ne sera renvoyé que dans les workflows basés sur les contacts. Les webhooks utilisés dans tous les autres types de workflows renverront uniquement la valeur la plus récente.

Vérifier les signatures de demande dans les webhooks de workflows

Une fois que vous avez sélectionné Signature de demande dans la section Authentification pour votre action Déclencher un webhook, HubSpot remplira le webhook avec un en-tête X-HubSpot-Signature, avec une fonction de hachage SHA-256 de concaténation de l'app-secret pour votre application, la méthode HTTP, l'URI et le corps non analysé. Découvrez-en davantage sur ce point dans la documentation des développeurs.

Pour vérifier que les demandes reçues à votre URL proviennent de HubSpot :

• Ayez un compte développeur. Si vous n'en avez pas, ouvrez-en un.
• Possédez une application. Si vous n'en avez pas, découvrez comment créer une application.
• Vérifiez la valeur de hachage de la signature.

Déclencher des workflows à partir de webhooks

Les webhooks peuvent être utilisés pour déclencher des workflows. Lorsque les données d'une application tierce changent, cela peut déclencher un workflow. Découvrez-en davantage sur ledéclenchement de workflows à partir de webhooks.

Utiliser des données de webhook dans le panneau de données

Les données provenant du webhook connecté à votre compte peuvent être utilisées pour certaines actions dans le panneau de données.

Pour utiliser les données du webhook connecté :

1. Depuis votre compte HubSpot, accédez à Automatisation > Workflows.
2. Cliquez sur le nom de votre workflow.
3. Cliquez sur l'icône + pour ajouter une action.
4. Dans le panneau de gauche, sélectionnez une action qui utilise le panneau de données.
5. Dans le panneau de données, cliquez sur le menu déroulant Afficher les propriétés ou les résultats d'action à partir de et sélectionnez Déclencheur de webhook. Vous pouvez alors utiliser les propriétés du webhook connecté.