API d'automatisation | Actions de workflow personnalisées
Présentation et vue d’ensemble des extensions de workflows.
Dernière modification : 2 décembre 2025
Exigences de portée
Utilisez l’outil Workflows de HubSpot pour automatiser les processus commerciaux et améliorer l’efficacité des équipes. Vous pouvez créer des actions de workflow personnalisées pour intégrer votre service aux workflows de HubSpot.Après avoir configuré votre action personnalisée, lorsque les utilisateurs installeront votre application, ils pourront ajouter l’action personnalisée à leurs workflows.Lorsque ces workflows seront exécutés, les requêtes HTTPS seront envoyées à l’URL configurée avec la charge utile définie. Les requêtes effectuées pour votre action personnalisée utiliseront la version 2 de X-HubSpot-Signature. Découvrez-en davantage sur la validation des requêtes de HubSpot. Vous pouvez également passer aux sections suivantes :
Lorsque vous effectuez des requêtes aux points de terminaison d’action de workflow personnalisés, vous devez authentifier les appels à l’aide de jetons d’accès OAuth ou d’application privée. Découvrez-en davantage sur les méthodes d’authentification dans HubSpot.
Pour créer une action de workflow personnalisée, vous devez définir l’action à l’aide des champs suivants. Cela indique également le format de requête pour les requêtes provenant de HubSpot, ainsi que le traitement des réponses par votre service.
actionUrl : l’URL vers laquelle une requête HTTPS est envoyée lorsque l’action est exécutée. Le corps de la requête contient des informations sur l’utilisateur au nom duquel l’action est exécutée et sur les valeurs saisies pour les champs de saisie.
objectTypes : les objets CRM avec lesquels cette action peut être utilisée.
published : par défaut, les actions personnalisées sont créées dans un état non publié. Les actions non publiées ne sont visibles que dans le portail de développeur associé à votre application HubSpot. Pour rendre votre action personnalisée visible par les utilisateurs, mettez à jour l’indicateur published de votre définition d’action et définissez-le sur true.
inputFields : les entrées reçues par l’action. Celles-ci seront renseignées par l’utilisateur.
inputFieldDependencies : ces règles définissent les relations entre deux ou plusieurs entrées, en fonction de leur dependencyType, comme dans cet exemple. Vous pouvez utiliser les options dependencyType suivantes :
SINGLE_FIELD : ces règles permettent de griser les champs jusqu’à ce que les autres champs répondent à des conditions spécifiques. Utilisez cette option pour vous assurer qu’un champ est pré-rempli avant de permettre aux visiteurs de continuer à remplir le reste du formulaire. Les champs de contrôle (parents) fourniront des valeurs aux champs dépendants (enfants) correspondants.
CONDITIONAL_SINGLE_FIELD : ces règles permettent de masquer les champs jusqu’à ce que les autres champs répondent à des conditions spécifiques. Utilisez cette option pour afficher ou masquer des champs spécifiques en fonction d’une sélection précédente. Par exemple, si votre entreprise est une boulangerie, vous pouvez ajouter une case à cocher pour demander aux visiteurs s’ils aiment les gâteaux et, uniquement si la case est cochée, afficher un champ pour demander quelle saveur de gâteau ils préfèrent.
outputFields : les valeurs résultantes de l’action qui peuvent être utilisées par des actions suivantes dans le workflow. Une action personnalisée peut avoir aucun, un ou plusieurs résultats.
objectRequestOptions : propriétés de l’objet inscrit incluses dans la charge utile de actionUrl.
labels : une copie qui décrit pour l’utilisateur ce que représentent les champs de l’action et ce que fait l’action. Des libellés en anglais sont requis, mais les libellés peuvent également être indiqués dans l’une de ces langues prises en charge :
Français (fr)
Allemand (de)
Japonais (ja)
Espagnol (es)
Portugais, Brésil (pt-br)
Néerlandais (nl)
Polonais (pl)
Suédois (sv)
Italien (it)
Danois, Danemark (da_dk)
Finnois (fi)
Norvégien (no)
Chinois traditionnel, Taïwan (zh-tw)
executionRules : une liste des définitions que vous pouvez spécifier pour identifier les erreurs de votre service vers l’utilisateur qui crée le workflow.
functions : les blocs de code qui sont exécutés afin de transformer la charge utile envoyée vers une URL et/ou de transformer la réponse à partir de cette URL.
La définition ci-dessus restituera ce qui suit dans l’outil Workflows :
Il existe deux types d’appels effectués pour les actions de workflow personnalisées :
Récupérations d’options de champ : renseignez une liste des options valides lorsqu’un utilisateur configure un champ. Découvrez-en davantage sur l’utilisation des options de champ pour récupérer des champs de données externes.
Requêtes d’exécution d’action : effectué lorsqu’une action est exécutée par un workflow qui comprend votre action personnalisée.
Les fonctions sont des blocs de code utilisés pour modifier les charges utiles avant de les envoyer à une API. Vous pouvez également utiliser des fonctions pour analyser les résultats d’une API. Les fonctions de HubSpot reposent sur AWS Lambda. Dans le code suivant :
event contient les données qui sont transmises à la fonction.
exports.main est la méthode qui sera appelée lors de l’exécution de la fonction.
La fonction callback peut être utilisée pour renvoyer un résultat.
Lors de la configuration d’une fonction, le format functionSource sera dans la chaîne. Assurez-vous que les caractères du code ont été échappés.Généralement, la définition d’une fonction suit le format suivant :
Les définitions des champs de saisie seront conformes au format suivant :
name : le nom interne du champ de saisie, différent de son libellé. Le libellé affiché dans l’interface utilisateur doit être défini à l’aide de la section Libellés de la définition d’action personnalisée.
type : le type de valeur requis par la saisie.
fieldType : comment le champ de saisie doit être rendu dans l’interface utilisateur. Les champs de saisie imitent les propriétés CRM. Découvrez-en davantage sur les combinaisons valides entre type et fieldType.
supportedValueTypes compte deux valeurs valides :
OBJECT_PROPERTY : l’utilisateur peut sélectionner une propriété à partir de l’objet inscrit ou un résultat d’une action précédente à utiliser comme valeur du champ.
STATIC_VALUE : doit être utilisé dans tous les autres cas. Cela signifie que l’utilisateur doit saisir lui-même une valeur.
isRequired : détermine si l’utilisateur doit donner ou non une valeur pour cette entrée.
Les définitions des champs de saisie doivent être formatées comme suit :
Au lieu de coder des options de champ en dur, vous pouvez également récupérer des données externes avec des champs de données externes. Par exemple, vous pouvez récupérer une liste de projets de réunion ou une liste de produits pour vos saisies.
Pour transmettre des données d’entrée à d’autres entrées, vous devez définir leur relation avec l’utilisation de inputFieldDependencies. Découvrez-en davantage sur la définition de votre action personnalisée.
Votre version de définition d’action personnalisée.
objectTypeId
Le type d’objet du workflow dans lequel l’action est utilisée.
inputFieldName
Le champ de saisie pour lequel vous récupérez des options.
inputFields
Les valeurs pour les champs qui ont déjà été remplis par l’utilisateur du workflow.
q
La requête de recherche fournie par l’utilisateur. Cela doit être utilisé pour filtrer les options renvoyées. Cela ne sera inclus que si la récupération d’option précédente a renvoyé searchable: true et que l’utilisateur a saisi une requête de recherche.
after
Le curseur de pagination. Il s’agira du même curseur de pagination que celui renvoyé par l’option fetch précédente. Il peut être utilisé pour garder une trace des options qui ont déjà été récupérées.
La réponse attendue devrait être formatée comme suit :
Le curseur de pagination. Si cela est fourni, l’application Workflows affichera un bouton pour charger plus de résultats en bas de la liste des options lorsqu’un utilisateur sélectionne une option. Lorsque la page suivante est chargée, cette valeur sera incluse dans la charge utile de la requête sous fetchOptions.after. Ce champ est facultatif.
after
La valeur par défaut est définie sur false. Dans le cas true, l’application Workflows affichera un champ de recherche pour permettre à un utilisateur de filtrer les options disponibles en fonction d’une requête de recherche. Lorsqu’une requête de recherche est saisie, les options seront à nouveau récupérées avec ce terme de recherche dans la charge utile de la requête sous fetchOptions.q. Ce champ est facultatif.
Dans le code ci-dessus, notez qu’une pagination est définie pour limiter le nombre d’options renvoyées. Cela indique au workflow que davantage d’options peuvent être chargées.De plus, la liste des options est consultable en incluant le code searchable:true.
Lorsqu’elle est incluse, cette fonction s’appliquera à chaque champ de saisie. Vous pouvez l’appliquer à un champ de saisie spécifique en spécifiant un id dans la définition de fonction.
Votre version de définition d’action personnalisée.
objectTypeId
Le type d’objet du workflow dans lequel l’action est utilisée.
inputFieldName
Le champ de saisie pour lequel vous récupérez des options.
inputFields
Les valeurs pour les champs qui ont déjà été remplis par l’utilisateur du workflow.
q
La requête de recherche fournie par l’utilisateur. Cela doit être utilisé pour filtrer les options renvoyées. Cela ne sera inclus que si la récupération d’option précédente a renvoyé searchable: true et que l’utilisateur a saisi une requête de recherche.
after
Le curseur de pagination. Il s’agira du même curseur de pagination que celui renvoyé par l’option fetch précédente. Il peut être utilisé pour garder une trace des options qui ont déjà été récupérées.
La réponse doit ensuite être formatée comme suit :
Le format du corps de requête. Cet élément est facultatif.
httpHeaders
Un mappage d’en-têtes de requête personnalisés à ajouter. Cet élément est facultatif.
contentType
Le Content-Type de la requête. La valeur par défaut est définie sur application/json. Cet élément est facultatif.
accept
Le type d’alerte Accept. La valeur par défaut est définie sur application/json. Cet élément est facultatif.
httpMethod
La méthode HTTP avec laquelle effectuer la requête. La valeur par défaut est POST, mais d’autres valeurs valides sont GET, POST, PUTPATCH, et DELETE. Cet élément est facultatif.
Pour analyser la réponse dans un format attendu, en fonction des champs de données externes, utilisez une fonction POST_FETCH_OPTIONS. La définition d’une fonction POST_FETCH_OPTIONS est identique à celle d’une fonction PRE_FETCH_OPTIONS. Lorsque des options de récupération de données externes sont définies, un menu déroulant sera affiché dans les options de saisie pour l’action.
Utilisez les champs de sortie pour générer des valeurs de votre action personnalisée à utiliser dans d’autres actions. La définition des champs de sortie est similaire à la définition des champs de saisie :
name : référencement de ce champ dans d’autres parties de l’action personnalisée. Le libellé affiché dans l’interface utilisateur doit être défini à l’aide de la section `labels` de l’action personnalisée.
type : le type de valeur requis par la saisie.
fieldType : comment le champ de saisie doit être rendu dans l’interface utilisateur. Les champs de saisie imitent les propriétés CRM. Découvrez-en davantage sur les combinaisons valides entre type et fieldType.
Lors de l’utilisation d’un champ de sortie, les valeurs sont analysées à partir de la réponse de actionURL. Par exemple, vous pouvez copier des champs de sortie dans une propriété existante dans HubSpot.**
Utilisez des libellés pour ajouter du texte à vos sorties ou entrées dans l’éditeur de workflow. Les libellés sont chargés dans le service de langue de HubSpot et leur affichage peut prendre quelques minutes. Les portails configurés pour différentes régions ou langues afficheront le libellé dans la langue correspondante, le cas échéant.
labels : une copie qui décrit ce que représentent les champs de l’action et ce que fait l’action. Des libellés en anglais sont requis, mais les libellés peuvent également être indiqués dans l’une de ces langues prises en charge : français (fr), allemand (de), japonais (ja), espagnol (es), portugais du Brésil (pt-br) et néerlandais (nl).
actionName : nom de l’action affiché dans le panneau Sélectionner une action de l’éditeur de workflow.
actionDescription : une description détaillée de l’action affichée lorsque l’utilisateur configure l’action personnalisée.
actionCardContent : une description récapitulative affichée dans la carte de l’action.
appDisplayName : Le nom de la section du panneau Choisir une action où toutes les actions de l’application sont affichées. Si appDisplayName est défini pour plusieurs actions, la première trouvée est utilisée.
inputFieldLabels : un objet qui regroupe les définitions de inputFields vers les libellés correspondants que l’utilisateur verra lors de la configuration de l’action.
outputFieldLabels : un objet qui regroupe les définitions de outputFields vers les libellés correspondants indiqués dans l’outil Workflows.
inputFieldDescriptions : un objet qui regroupe les définitions de inputFields vers les descriptions sous les libellés correspondants.
executionRules : un objet qui regroupe les définitions de executionRules vers des messages qui seront affichés pour les résultats d’exécution d’action dans l’historique du workflow. Il existe une section distincte dans ces documents pour les règles d’exécution.
Les définitions des libellés doivent être formatées comme suit :
Falschen Code melden
Kopieren
KI fragen
// { "labels":{ "en":{ "actionName":"Create Widget", "actionDescription":"This action will create a new widget in our system. So cool!", "actionCardContent":"Create widget {{widgetName}}", "appDisplayName":"My App Display Name", "inputFieldLabels":{ "widgetName":"Widget Name", "widgetOwner":"Widget Owner" }, "outputFieldLabels":{ "outputOne":"First Output" }, "inputFieldDescriptions":{ "widgetName":"Enter the full widget name. I support <a href=\"https://hubspot.com\">links</a> too." }, "executionRules":{ "alreadyExists":"The widget with name {{ widgetName }} already exists" } } }}
outputFields : les valeurs des champs de sortie définis précédemment. Ces valeurs peuvent être utilisées dans des actions ultérieures.
hs_execution_state : une valeur spéciale facultative qui peut être ajoutée à outputFields. Il n’est pas possible de spécifier une nouvelle tentative. Seules les valeurs suivantes peuvent être ajoutées :
SUCCESS
FAIL_CONTINUE
BLOCK
ASYNC
SUCCESS et FAIL_CONTINUE indiquent que l’action est terminée et que le workflow doit passer à l’action suivante à exécuter. Si aucun statut d’exécution n’est spécifié, des codes de statut seront utilisés pour déterminer le résultat d’une action :
Codes de statut 2xx : l’action a été correctement effectuée.
Codes de statut 4xx : l’action a échoué. Les codes de statut Taux limité 429 sont l’exception. Ces derniers sont traités comme des nouvelles tentatives et l’en-tête Retry-After est respecté.
Codes de statut 5xx : un problème temporaire est survenu avec le service et l’action sera relancée ultérieurement. Un système d’intervalle exponentiel est utilisé pour les nouvelles tentatives, qui se poursuivront pendant 3 jours au maximum avant d’échouer.
Utilisez les fonctions d’exécution pour formater les données avant de les envoyer vers actionURL et analysez les données de actionURL. Il existe deux types de fonctions d’exécution :
Utilisez les fonctions PRE_ACTION_EXECUTION pour formater les données avant de les envoyer vers actionURL.La définition de la fonction sera formatée comme suit :
La sortie de fonction doit être formatée comme suit :
Falschen Code melden
Kopieren
KI fragen
//{ // The webhook URL for HubSpot to call "webhookUrl": "https://myapi.com/hubspot", // Optional. The request body. "body": "{\"widgetName\": \"My new widget\", \"widgetColor\": \"blue\"}", // Optional. A map of custom request headers to add. "httpHeaders": { "My-Custom-Header": "header value" }, // Optional. The Content-Type of the request. Default is application/json. "contentType": "application/json", // Optional. The Accept type of the request. Default is application/json. "accept": "application/json", // Optional. The HTTP method with which to make the request. // Valid values are GET, POST, PUT, PATCH, and DELETE. // Default is POST. "httpMethod": "POST"}
Après avoir reçu une réponse de actionURL, utilisez une fonction POST_ACTION_EXECUTION pour formater les données pour HubSpot.La définition de la fonction sera formatée comme suit :
Utilisez des actions personnalisées pour bloquer l’exécution du workflow. Au lieu d’exécuter l’action suivante dans le workflow une fois que votre action personnalisée a reçu une réponse completed (2xx or 4xx status code) de votre service, le workflow cessera d’exécuter (« bloquera ») cette inscription tant que vous n’indiquerez pas au workflow de poursuivre.Lors du blocage, vous pouvez spécifier une valeur pour le champ hs_default_expiration, après quoi votre action personnalisée sera considérée comme expirée. L’exécution du workflow reprendra alors et l’action suivant votre action personnalisée sera exécutée, même si l’action n’est pas terminée.Pour bloquer une action personnalisée, la réponse de l’exécution de votre action doit avoir le format suivant :
Pour bloquer l’exécution du Workflow, cette option doit être définie sur BLOCK pour votre action personnalisée. Ce champ est obligatoire.
hs_expiration_duration
La durée doit être spécifiée au format ISO 8601 Durée. Si ce champ n’est pas renseigné, un délai d’expiration par défaut de 1 semaine sera utilisé. Cet élément est facultatif.
Pour terminer une exécution d’action personnalisée bloquée, utilisez le point de terminaison suivant : /callbacks/{callbackId}/complete.Formatez le corps de la requête comme suit :
L’état d’exécution final. Ce champ est obligatoire. Les valeurs valides pour ce champ sont SUCCESS pour indiquer que votre action personnalisée s’est correctement terminée et FAIL_CONTINUE pour indiquer qu’il y a un problème avec l’exécution de votre action personnalisée.
Ajouter des messages d’exécution personnalisés avec des règles
Spécifiez des règles sur votre action qui déterminent le message à afficher sur la page d’historique des workflows lorsque l’action est exécutée.Les règles seront associées aux valeurs de sortie de votre action. Ces valeurs de sortie doivent être fournies dans le corps de réponse de actionURL, au format suivant :
Les véritables messages peuvent être spécifiés dans la section Libellés de l’action personnalisée :
Falschen Code melden
Kopieren
KI fragen
//{ "labels": { "executionRules": { "alreadyExists": "The widget with name {{ widgetName }} already exists", "widgetWrongSize": "Wrong widget size", "widgetInvalidSize": "Invalid widget size" } } }}
Les règles executionRules seront testées dans l’ordre indiqué. S’il existe plusieurs correspondances, seul le message de la première règle correspondante s’affichera pour l’utilisateur.La règle est associée lorsque le résultat d’exécution correspond à une valeur spécifique dans la règle. Prenons l’exemple de cet ensemble de règles executionRules :
Falschen Code melden
Kopieren
KI fragen
//[ { // This matches the key of a label on the action's `labels.LANGUAGE.executionRules` map "labelName": "alreadyExists", "conditions": { "errorCode": "ALREADY_EXISTS" } }, { "labelName": "widgetWrongSize", "conditions": { "errorCode": "WIDGET_SIZE", "sizeError": ["TOO_SMALL", "TOO_BIG"] } }, { "labelName": "widgetInvalidSize", "conditions": { "errorCode": "WIDGET_SIZE" } }]
Les correspondances suivantes se produiront :
{"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"} : Cela correspond à la première règle, car errorCode équivaut à ALREADY_EXISTS. Dans cet exemple, même s’il y a un résultat widgetName, il ne sera pas utilisé dans la définition de la règle. Ainsi, toute valeur sera autorisée.
{"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"} : Cela correspond à la deuxième règle, car TOO_SMALL est l’un des éléments sizeError correspondants et errorCode est WIDGET_SIZE.
{"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}Cela correspond à la troisième règle, car même si errorCode est WIDGET_SIZE, sizeError ne correspond pas à l’une des valeurs spécifiées par la deuxième règle (TOO_SMALL ou TOO_BIG).
Ce mécanisme correspondant vous permet de spécifier des erreurs de secours afin que vous puissiez obtenir des erreurs spécifiques pour des cas d’erreur importants, mais des messages d’erreur plus génériques pour des erreurs moins courantes. Voici un exemple d’affichage du message personnalisé :
Tester des actions personnalisées avant publication
Avant de publier votre action personnalisée, vous pouvez tester les options d’exécution et de récupération de l’action en pointant l’URL vers webhook.site. Cela vous permet d’inspecter la charge utile et de renvoyer une réponse spécifique.Vous pouvez également tester l’action dans votre portail de développeur en créant un workflow dans l’outil Workflows. Puis, ajoutez votre nouvelle action.Lorsque vous avez terminé vos tests, il est recommandé d’archiver vos actions de test. Pour en savoir plus sur les actions d’archivage, consultez la documentation de référence.
Par défaut, les actions personnalisées sont créées dans un état non publié. Les actions personnalisées non publiées ne sont visibles que dans le portail du développeur associé à l’application HubSpot correspondante. Pour rendre votre action personnalisée visible par les utilisateurs, mettez à jour l’indicateur published de votre définition d’action et définissez-le sur true. Si une action n’est pas publiée, les portails qui ont déjà ajouté l’action à leur workflow pourront toujours modifier et exécuter les actions déjà ajoutées. Cependant, ils ne seront pas en mesure d’ajouter l’action à nouveau.
Les blocs de code ci-dessous fournissent des exemples de plusieurs cas d’utilisation courants pour des actions personnalisées, telles que la définition d’un widget ou l’appel d’une fonction sans serveur.
L’action personnalisée suivante utilise une fonction sans serveur pour transformer la charge utile envoyée à l’élément actionUrl configuré. Étant donné que le champ objectTypes n’est pas spécifié dans la définition d’action personnalisée, cette action sera disponible dans tous les types de workflows.
L’action personnalisée suivante contient des dépendances de champs et des options récupérées depuis une API externe. Étant donné que la taille du widget dépend de la couleur du widget, l’utilisateur ne pourra pas saisir une valeur pour la taille du widget tant qu’il n’aura pas choisi une couleur.Le coût du widget dépend également de la couleur du widget, mais il dépend de la valeur que l’utilisateur sélectionne pour la couleur du widget. L’utilisateur ne pourra pas saisir une valeur pour le coût du widget, sauf si la couleur rouge est sélectionnée comme couleur du widget.
