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 :

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

• Envoi d'alertes sur le chat depuis votre système externe vers le flux de chat de votre entreprise afin que vos salariés soient informés des événements importants.

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

Configurer un webhook dans un workflow

• Dans votre compte HubSpot, accédez à Automatisations > Workflows.
• Cliquez sur le nom du workflow.
• Cliquez sur l' icône plus (+) pour ajouter une action.
• Dans le panneau de gauche, sélectionnez Send a webhook.
• Cliquez sur le menu déroulant Méthode, puis sélectionnez POST ou 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 : 
  • 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.

• • Vous pouvez également utiliser une clé d'API ou une application publique créée par le biais d'un compte de développeur pour l'authentification.

Remarque : À compter du 30 novembre 2022, les clés d'API HubSpot sont obsolètes et ne sont plus prises en charge. Vous pouvez toujours utiliser des clés d'API externes pour l'authentification dans les workflows HubSpot.

• • • 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'une de nos 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.
• Si vous configurez une demande POST, vous pouvez choisir d'inclure toutes les propriétés de la fiche d'informations de CRM ou de n'envoyer que des propriétés spécifiques :
  • Pour inclure toutes les propriétés, dans la section Personnaliser le corps de la recherche, sélectionnez Inclure toutes les propriétés. 
  • Pour inclure uniquement certaines propriétés :
    
    • Dans la section Personnaliser le corps de la recherche, sélectionnez Sélectionner les propriétés spécifiques.
    • Cliquez sur le menu déroulant Choisir une propriété. Ensuite, cliquez sur [objet] dans ce workflow et sélectionnez une propriété.
    • Pour modifier le nom d'une propriété dans le webhook, modifiez le champ de texte Nom de la propriété. Cela mettra à jour uniquement le nom de la propriété dans la demande POST, et pas le nom de la propriété ou le nom interne dans HubSpot. 
    • Pour ajouter une autre propriété, cliquez sur Ajouter une propriété.
    • Pour supprimer une propriété, cliquez sur l'icône Corbeille delete.
       

• Si vous configurez une demande GET, vous pouvez utiliser des propriétés comme paramètres de demande :
  
  • Dans la section Paramètres de demande, cliquez sur le menu déroulant Choisir une propriété. Ensuite, cliquez sur [objet] dans ce workflow et sélectionnez une propriété.
  • Pour modifier le nom d'une propriété dans le paramètre de demande, modifiez le champ de texte Nom de la propriété. Cela mettra à jour uniquement le nom de la propriété dans la demande GET, et pas le nom de la propriété ou le nom interne dans HubSpot. 
  • Pour ajouter une autre propriété, cliquez sur Ajouter un paramètre de requête.
  • Pour supprimer une propriété, cliquez sur l'icône Corbeille delete. 
• Cliquez sur Enregistrer.
  
  

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

Personnaliser votre demande POST

Si vous configurez une demande POST, vous pouvez choisir d'inclure toutes les propriétés de la fiche d'informations de CRM ou de n'envoyer que des propriétés spécifiques :

• Pour inclure toutes les propriétés, dans la section Personnaliser le corps de la recherche, sélectionnez Inclure toutes les propriétés. 
• Pour inclure uniquement certaines propriétés :
  
  • Dans la section Corps de la demande, sélectionnez Personnaliser le corps de la demande.
  • Saisissez la clé et la valeur.
  • Pour modifier le nom d'une propriété dans le webhook, modifiez le champ de texte Clé. Cela mettra à jour uniquement le nom de la propriété dans la demande POST, et pas le nom de la propriété ou le nom interne dans HubSpot. 
  • Pour ajouter une autre propriété, cliquez sur Ajouter une propriété.
  • Pour supprimer une propriété, cliquez sur l'icône Corbeille delete. 
    
    

Personnaliser vos demandes GET

Si vous configurez une demande GET, vous pouvez utiliser des propriétés comme paramètres de demande pour récupérer des données spécifiques : 

• Dans la section Paramètres de demande, saisissez la clé, puis sélectionnez une propriété.
• Pour modifier le nom d'une propriété dans le paramètre de demande, modifiez le champ de texte Nom de la propriété. Cela mettra à jour uniquement le nom de la propriété dans la demande GET, et pas le nom de la propriété ou le nom interne dans HubSpot. 
• Pour ajouter une autre propriété, cliquez sur Ajouter une propriété.
• Pour supprimer une propriété, cliquez sur l'icône Corbeille delete. 
• Sélectionnez un type d'authentification dans le menu déroulant.
• Cliquez sur Enregistrer.
  
  

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. 

• Dans le panneau latéral, cliquez sur Tester l'action pour développer la section. 
• Cliquez sur le menu déroulant Objet, puis sélectionnez une Fiche d'informations à 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 que votre workflow a été activé, vous pouvez inscrire manuellement un contact de test. 

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 le panneau de données, sous Enrollment properties, vous pouvez sélectionner l'une des propriétés du webhook connecté.