Utiliser 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. Les cas d'utilisation les plus fréquents incluent :

• L'envoi des données de contact HubSpot à un autre système, tel qu'un CRM, lorsque ce contact remplit un formulaire particulier sur 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 réessayent pas après avoir reçu des codes d'état de réponse de la série 4XX.
Les erreurs de limite de débit 429 constituent une exception à cette règle ; les Workflows réessayent automatiquement après avoir reçu une réponse 429 et respectent l'en-tête Retry-After s'il est présent. Le délai de réessai 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.

Mise en place d'une requête POST

• Dans votre compte HubSpot, accédez à Automatisations > Workflows.
• Pour modifier un workflow existant, cliquez sur le nom du workflow. Ou bien, créer un nouveau workflow.
• Dans l'éditeur de workflow, cliquez sur l'icône + plus pour ajouter une action.
• Dans le panneau de gauche, dans la section Data ops, sélectionnez Send a webhook.
   

• Cliquez sur le menu déroulant Method et sélectionnez POST. 
• 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 ?queryparameter=abc à l'URL du webhook.
  • Si aucun paramètre de demande n'a été ajouté, une demande POST ou GET générique sera envoyée. 
• 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é 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é 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 à l'API de 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.

• Pour inclure toutes les propriétés, sélectionnez Inclure toutes les propriétés [de l'objet]. 
• 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, entrez 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 de la corbeille delete .
• Cliquez sur Enregistrer. 

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

Préparer une requête GET

• Dans votre compte HubSpot, accédez à Automatisations > Workflows.
• Pour modifier un workflow existant, cliquez sur le nom du workflow. Ou bien, créer un nouveau workflow.
• Dans l'éditeur de workflow, cliquez sur l'icône + plus pour ajouter une action.
• Dans le panneau de gauche, dans la section Data ops, sélectionnez Send a webhook.
   

• Cliquez sur le menu déroulant Method et sélectionnez GET. 
• 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 ?queryparameter=abc à l'URL du webhook.
  • Si aucun paramètre de demande n'a été ajouté, une demande POST ou GET générique sera envoyée. 
• 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é 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é 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 à l'API de 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.

• Pour utiliser une propriété HubSpot comme paramètre de requête : 
  • 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 Corbeille delete. 
• Pour utiliser une valeur statique comme paramètre de requête : 
  • Dans la section Paramètres d'interrogation , entrez la clé , puis entrez une valeur.
  • Pour ajouter une autre propriété, cliquez sur Ajouter une valeur statique.
  • Pour supprimer une propriété, cliquez sur l'icône Corbeille delete. 
• Cliquez sur Enregistrer. 

Testez 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. 

• Dans votre compte HubSpot, accédez à Automatisations > Workflows.
• Cliquez sur le nom du workflow. 
• Dans l'éditeur de workflow, cliquez sur l'action Send a webhook.
• Dans le panneau de gauche, cliquez sur Test action pour développer la section. 
• Si vous testez une requête POST, cliquez sur le menu déroulant [object], puis sélectionnez un enregistrement à tester.
• Cliquez sur Tester. 
• 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.

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

• 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 des données sont modifiées dans une application tierce, cela peut déclencher un workflow. Découvrez-en davantage sur ledéclenchement de workflows à partir de webhooks.

Utiliser les données du webhook dans l'écran de contrôle

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é à :

• Dans votre compte HubSpot, accédez à Automatisations > Workflows.
• Cliquez sur le nom de votre workflow.
• Cliquez sur l'icône + plus pour ajouter une action.
• Dans le panneau de gauche, sélectionnez une action qui utilise le panneau de données .
• Dans l'écran de contrôle, cliquez sur le menu déroulant View properties or action outputs from et sélectionnez Webhook trigger. Vous pouvez alors utiliser les propriétés du webhook connecté.