Passer au contenu principal
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 : La dernière section de cet article fournit plusieurs exemples d’actions personnalisées.

​
Avant de commencer

​
Définir votre action personnalisée

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.

​
Exemple de définition d’action personnalisée

//
{
  "actionUrl": "https://webhook.site/94d09471-6f4c-4a7f-bae2-c9a585dd41e0",
  "objectTypes": ["CONTACT"],
  "inputFields": [
    {
      "typeDefinition": {
        "name": "staticInput",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "objectInput",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "optionsInput",
        "type": "enumeration",
        "fieldType": "select",
        "optionsUrl": "https://webhook.site/94d09471-6f4c-4a7f-bae2-c9a585dd41e0"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    }
  ],
  "inputFieldDependencies": [
    {
      "dependencyType": "SINGLE_FIELD",
      "dependentFieldNames": ["objectInput"],
      "controllingFieldName": "staticInput"
    }
  ],
  "outputFields": [
    {
      "typeDefinition": {
        "name": "myOutput",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    }
  ],
  "objectRequestOptions": {
    "properties": ["email"]
  },
  "labels": {
    "en": {
      "inputFieldLabels": {
        "staticInput": "Static Input",
        "objectInput": "Object Property Input",
        "optionsInput": "External Options Input"
      },
      "actionName": "My Extension",
      "actionDescription": "My Extension Description",
      "appDisplayName": "My App Display Name",
      "actionCardContent": "My Action Card Content"
    }
  },
  "functions": [
    {
      "functionType": "POST_ACTION_EXECUTION",
      "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    outputFields: {\r\n      myOutput: \"example output value\"\r\n    }\r\n  });\r\n}"
    },
    {
      "functionType": "POST_FETCH_OPTIONS",
      "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    \"options\": [{\r\n        \"label\": \"Big Widget\",\r\n        \"description\": \"Big Widget\",\r\n        \"value\": \"10\"\r\n      },\r\n      {\r\n        \"label\": \"Small Widget\",\r\n        \"description\": \"Small Widget\",\r\n        \"value\": \"1\"\r\n      }\r\n    ]\r\n  });\r\n}"
    }
  ]
}
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.

​
Fonctions

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.
Le code doit être formaté comme suit : 
exports.main = (event, callback) => {
  callback({
    "data": {
      "field": "email",
      "phone": "1234567890"
    }
  });
}
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 : 
//
{
  "functionType": "PRE_ACTION_EXECUTION",
  "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    \"data\": {\r\n      \"field\": \"email\",\r\n      \"phone\": \"1234567890\" \r\n    }\r\n  });\r\n"
}

​
Exemple de fonction

Dans l’exemple ci-dessous, examinez le code saisi, la fonction utilisée et le résultat. Saisie de fonction : 
//
{
  "callbackId": "ap-102670506-56777914962-11-0",
  "origin": {
    "portalId": 102670506,
    "actionDefinitionId": 10860211,
    "actionDefinitionVersion": 1,
    "extensionDefinitionId": 10860211,
    "extensionDefinitionVersionId": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 192814114
  },
  "object": {
    "objectId": 614,
    "objectType": "CONTACT"
  },
  "inputFields": {
    "widgetOwner": "10887165",
    "widgetName": "My Widget Name"
  }
}
Fonction utilisée : 
//
exports.main = (event, callback) => {
  callback({
    "data": {
      "myObjectId": event["object"]["objectId"],
      "myField": event["inputFields"]["widgetName"]
    }
  });
}
Résultats escomptés : 
//
{
  "data": {
    "myObjectId": 614,
    "myField": "My Widget Name"
  }
}

​
Champs de saisie

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 : 
//
{
  "typeDefinition": {
    "name": "staticInput",
    "type": "string",
    "fieldType": "text"
  },
  "supportedValueTypes": ["STATIC_VALUE"],
  "isRequired": true
}
Vous pouvez également coder des options en dur pour l’utilisateur : 
//
{
  "typeDefinition": {
    "name": "widgetColor",
    "type": "enumeration",
    "fieldType": "select",
    "options": [
      {
        "value": "red",
        "label": "Red"
      },
      {
        "value": "blue",
        "label": "Blue"
      },
      {
        "value": "green",
        "label": "Green"
      }
    ]
  },
  "supportedValueTypes": ["STATIC_VALUE"]
}

​
Utiliser des données externes

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.

​
Remarque :

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.
Le champ de saisie doit être formaté comme suit : 
//
{
  "typeDefinition": {
    "name": "optionsInput",
    "type": "enumeration",
    "fieldType": "select",
    "optionsUrl": "https://your-url-here.com"
  },
  "supportedValueTypes": ["STATIC_VALUE"]
}
La charge utile envoyée à optionsURL sera formatée comme suit : 
//
{
  "origin": {
    "portalId": 1,
    "actionDefinitionId": 2,
    "actionDefinitionVersion": 3
  },

  "objectTypeId": "0-1",
  "inputFieldName": "optionsInput",
  "inputFields": {
    "widgetName": {
      "type": "OBJECT_PROPERTY",
      "propertyName": "widget_name"
    },
    "widgetColor": {
      "type": "STATIC_VALUE",
      "value": "blue"
    }
  },

  "fetchOptions": {
    "q": "option label",
    "after": "1234="
  }
}
ChampDescription
portalIdL’ID du compte HubSpot.
actionDefinitionIdVotre ID de définition d’action personnalisée.
actionDefinitionVersionVotre version de définition d’action personnalisée.
objectTypeIdLe type d’objet du workflow dans lequel l’action est utilisée.
inputFieldNameLe champ de saisie pour lequel vous récupérez des options.
inputFieldsLes valeurs pour les champs qui ont déjà été remplis par l’utilisateur du workflow.
qLa 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.
afterLe 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 : 
//
{
  "options": [
    {
      "label": "Big Widget",
      "description": "Big Widget",
      "value": "10"
    },
    {
      "label": "Small Widget",
      "description": "Small Widget",
      "value": "1"
    }
  ],

  "after": "1234=",
  "searchable": true
}
ChampDescription
qLe 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.
afterLa 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.

​
Modifier des données externes

Pour gérer les données externes, vous pouvez inclure deux hooks pour personnaliser le cycle de vie de la récupération d’options de champ :
  • PRE_FETCH_OPTIONS : une fonction qui configure la charge utile envoyée depuis HubSpot.
  • POST_FETCH_OPTIONS : une fonction qui transforme la réponse de votre service dans un format pris en charge par HubSpot.

​
PRE_FETCH_OPTIONS

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. 
//
{
  "functionType": "PRE_FETCH_OPTIONS",
  "functionSource": "...",
  "id": "inputField"
}
La charge utile envoyée depuis HubSpot sera formatée comme suit : 
//
{
  "origin": {
    "portalId": 1,
    "actionDefinitionId": 2,
    "actionDefinitionVersion": 3
  },

  "inputFieldName": "optionsInput",
  "webhookUrl": "https://myapi.com/hubspot/widget-sizes",
  "inputFields": {
    "widgetName": {
      "type": "OBJECT_PROPERTY",
      "propertyName": "widget_name"
    },
    "widgetColor": {
      "type": "STATIC_VALUE",
      "value": "blue"
    },

    "fetchOptions": {
      "q": "option label",
      "after": "1234="
    }
  }
}
ChampDescription
portalIdL’ID du compte HubSpot.
actionDefinitionIdVotre ID de définition d’action personnalisée.
actionDefinitionVersionVotre version de définition d’action personnalisée.
objectTypeIdLe type d’objet du workflow dans lequel l’action est utilisée.
inputFieldNameLe champ de saisie pour lequel vous récupérez des options.
inputFieldsLes valeurs pour les champs qui ont déjà été remplis par l’utilisateur du workflow.
qLa 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.
afterLe 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 : 
//
{
  "webhookUrl": "https://myapi.com/hubspot",
  "body": "{\"widgetName\": \"My new widget\", \"widgetColor\": \"blue\"}",
  "httpHeaders": {
    "My-Custom-Header": "header value"
  },
  "contentType": "application/json",
  "accept": "application/json",
  "httpMethod": "POST"
}
ChampDescription
webhookUrlL’URL du webhook à appeler pour HubSpot.
bodyLe format du corps de requête. Cet élément est facultatif.
httpHeadersUn mappage d’en-têtes de requête personnalisés à ajouter. Cet élément est facultatif.
contentTypeLe Content-Type de la requête. La valeur par défaut est définie sur application/json. Cet élément est facultatif.
acceptLe type d’alerte Accept. La valeur par défaut est définie sur application/json. Cet élément est facultatif.
httpMethodLa méthode HTTP avec laquelle effectuer la requête. La valeur par défaut est POST, mais d’autres valeurs valides sont GET, POST, PUT PATCH, et DELETE. Cet élément est facultatif.

​
POST_FETCH_OPTIONS

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. 
//
{
  "functionType": "POST_FETCH_OPTIONS",
  "functionSource": "...",
  "id": "inputField"
}
La saisie de fonction sera formatée comme suit : 
//
{
  // The requested field key
  "fieldKey": "widgetSize",

  // The webhook response body from your service
  "responseBody": "{\"widgetSizes\": [10, 1]}"
}
La sortie de fonction sera formatée comme suit : 
//
{
  "options": [
    {
      "label": "Big Widget",
      "description": "Big Widget",
      "value": "10"
    },
    {
      "label": "Small Widget",
      "description": "Small Widget",
      "value": "1"
    }
  ]
}

​
Champs de sortie

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.
Le champ de sortie doit être formaté comme suit : 
//
{
  "outputFields": [
    {
      "typeDefinition": {
        "name": "myOutput",
        "type": "string",
        "fieldType": "text"
      }
    }
  ]
}
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. **
**

​
Libellés

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 : 
// {
  "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"
      }
    }
  }
}

​
Exécution

Lorsqu’une exécution survient, une requête HTTPM est envoyée à actionUrl.
  • callbackId** :** un ID unique pour l’exécution spécifique. Si l’exécution de l’action personnalisée est bloquée, utilisez cet ID.
  • object : les valeurs des propriétés demandées dans objectRequestOptions.
  • InputFields : les valeurs pour les saisies que l’utilisateur a renseignées.
La charge utile d’exécution sera formatée comme suit : 
// {
  "callbackId": "ap-102670506-56776413549-7-0",
  "origin": {
    "portalId": 102670506,
    "actionDefinitionId": 10646377,
    "actionDefinitionVersion": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 192814114
  },
  "object": {
    "objectId": 904,
    "properties": {
      "email": "[email protected]"
    },
    "objectType": "CONTACT"
  },
  "inputFields": {
    "staticInput": "My Static Input",
    "objectInput": "995",
    "optionsInput": "1"
  }
}
La réponse attendue devrait être formatée comme suit : 
//
{
  "outputFields": {
    "myOutput": "Some value",
    "hs_execution_state": "SUCCESS"
  }
}
Lors de l’examen de la réponse d’exécution :
  • 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.

​
Fonctions d’exécution

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 :
  • PRE_ACTION_EXECUTION
  • POST_ACTION_EXECUTION

​
Fonction PRE_ACTION_EXECUTION

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 : 
//
{
  "functionType": "PRE_ACTION_EXECUTION",
  "functionSource": "..."
}
La saisie de fonction doit être formatée comme suit : 
//
{
  "webhookUrl": "https://actionurl.com/",
  "callbackId": "ap-102670506-56776413549-7-0",
  "origin": {
    "portalId": 102670506,
    "actionDefinitionId": 10646377,
    "actionDefinitionVersion": 1
  },
  "context": {
    "source": "WORKFLOWS",
    "workflowId": 192814114
  },
  "object": {
    "objectId": 904,
    "properties": {
      "email": "[email protected]"
    },
    "objectType": "CONTACT"
  },
  "inputFields": {
    "staticInput": "My Static Input",
    "objectInput": "995",
    "optionsInput": "1"
  }
}
La sortie de fonction doit être formatée comme suit : 
//
{
  // 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"
}

​
Fonction POST_ACTION_EXECUTION

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 : 
//
{
  "functionType": "POST_ACTION_EXECUTION",
  "functionSource": "..."
}
La saisie de fonction doit être formatée comme suit : 
//
{
  "responseBody": "{\r\n  \"returnValue\":\"Hello World!\"\r\n}"
}
La sortie de fonction doit être formatée comme suit : 
//
{
  "outputFields": {
    "myOutput": "Some value",
    "hs_execution_state": "SUCCESS"
  }
}

​
Exécution asynchrone

Exécutez des actions de workflow personnalisées de manière asynchrone en bloquant, puis en finalisant l’action.

​
Bloquer l’exécution de l’action

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 : 
//
{
  "outputFields": {
    "hs_execution_state": "BLOCK",
    "hs_expiration_duration": "P1WT1H"
  }
}
ChampDescription
hs_execution_statePour 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_durationLa 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.

​
Terminer une exécution bloquée

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 : 
//
{
  "outputFields": {
    "hs_execution_state": "SUCCESS"
  }
}
ChampDescription
hs_execution_stateL’é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 : 
//
{
  "outputFields": {
    "errorCode": "ALREADY_EXISTS",
    "widgetName": "Test widget"
  }
}
Les véritables messages peuvent être spécifiés dans la section Libellés de l’action personnalisée : 
//
{
  "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 : 
//
[
  {
    // 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 et publier votre action personnalisée

Après avoir créé votre nouvelle action personnalisée, vous pouvez la tester et la publier.

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

​
Publier des actions personnalisées

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.

​
Exemples d’actions personnalisées

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.

​
Exemple #1

Cet exemple présente les champs de saisie suivants, créés pour les workflows de contact et de transaction :
  • widgetName : un champ de saisie statique
  • widgetColor : un champ déroulant avec des options
  • widgetOwner : un champ représentant un propriétaire HubSpot.
  • widgetQuantity : un champ dérivé d’une propriété (que l’utilisateur créant le workflow sélectionne) de l’objet inscrit.
//
{
  "actionUrl": "https://example.com/hubspot",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "widgetColor",
        "type": "enumeration",
        "fieldType": "select",
        "options": [
          { "value": "red", "label": "Red" },
          { "value": "blue", "label": "Blue" },
          { "value": "green", "label": "Green" }
        ]
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetOwner",
        "type": "enumeration",
        "referencedObjectType": "OWNER"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetQuantity",
        "type": "number"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"]
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 1",
      "actionDescription": "This action will create a new widget in our system. So cool!",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name",
        "widgetColor": "Widget Color",
        "widgetOwner": "Widget Owner",
        "widgetQuantity": "Widget Quantity"
      },
      "inputFieldDescriptions": {
        "widgetName": "Enter the full widget name. I support <a href=\"https://hubspot.com\">links</a> too.",
        "widgetColor": "This is the color that will be used to paint the widget."
      }
    }
  },
  "objectTypes": ["CONTACT", "DEAL"]
}

​
Exemple #2

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. 
//
{
  "actionUrl": "https://example.com",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 2",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name"
      }
    }
  },
  "functions": [
    {
      "functionType": "PRE_ACTION_EXECUTION",
      "functionSource": "exports.main = function(event, callback) { return callback(transformRequest(event)); }\nfunction transformRequest(request) { return { webhookUrl: request.webhookUrl, body: JSON.stringify(request.fields), contentType: 'application/x-www-form-urlencoded', accept: 'application/json', httpMethod: 'POST' }; }"
    }
  ]
}

​
Exemple #3

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. 
//
{
  "actionUrl": "https://example.com/hubspot",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "widgetColor",
        "type": "enumeration",
        "fieldType": "select",
        "options": [
          { "value": "red", "description": "red", "label": "Red" },
          { "value": "blue", "description": "blue", "label": "Blue" },
          { "value": "green", "description": "green", "label": "Green" }
        ]
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetSize",
        "type": "enumeration",
        "fieldType": "select",
        "optionsUrl": "https://api.example.com/v1/widget-sizes"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetCost",
        "type": "number",
        "fieldType": "number"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"]
    }
  ],
  "inputFieldDependencies": [
    {
      "dependencyType": "SINGLE_FIELD",
      "controllingFieldName": "widgetColor",
      "dependentFieldNames": ["widgetSize"]
    },
    {
      "dependencyType": "CONDITIONAL_SINGLE_FIELD",
      "controllingFieldName": "widgetColor",
      "controllingFieldValue": "red",
      "dependentFieldNames": ["widgetCost"]
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 3",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name",
        "widgetColor": "Widget Color",
        "widgetSize": "Widget Size",
        "widgetCost": "Widget Cost"
      }
    }
  },
  "objectTypes": ["CONTACT", "DEAL"],
  "functions": [
    {
      "functionType": "PRE_FETCH_OPTIONS",
      "id": "widgetSize",
      "functionSource": "exports.main = function(event, callback) { return callback(transformRequest(event)); }\nfunction transformRequest(request) { return { webhookUrl: request.webhookUrl + '?color=' + request.fields.widgetColor.value, body: JSON.stringify(request.fields), httpMethod: 'GET' }; }"
    }
  ]
}
Last modified on December 10, 2025