Dernière modification : 11 septembre 2025
Vous trouverez ci-dessous des informations de référence relatives à l’utilisation des événements d’application, notamment les schémas de type d’événement, les modèles de rendu de chronologie d’événement, les champs d’occurrence d’événement, etc.

​
Structure du projet

Dans le contexte d’un projet, vous placerez les définitions des types d’événements dans un répertoire app-events sous app/. Le répertoire app-events doit contenir un fichier de définition de schéma JSON pour chaque type d’événement (*-hsmeta.json). 
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
Pour inclure des définitions de types d’événement dans un projet, procédez comme suit :
  • Votre application doit utiliser l’authentification OAuth et être configurée pour la distribution sur le marketplace des applications. En outre, l’application doit inclure timeline dans son requiredScopes. Découvrez-en davantage sur la configuration de l’application.
  • Votre projet doit être correctement déployé avant de pouvoir inclure un composant d’événement d’application.

​
Schéma de type d’événement

Voici les options de configuration disponibles pour les schémas de type d’événement (*-hsmeta.json). Notez que certains des attributs ci-dessous ne peuvent pas être modifiés après la création du type d’événement.
Chaque application est limitée à 750 types d’événements.
{
 "uid": "customer_login_event",
 "type": "app-event",
 "config": {
   "name": "Customer login",
   "headerTemplate": "{{customerName}} logged in.",
   "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
   "objectType": "CONTACT",
   "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]
 }
}

Les champs marqués par * sont requis.

ChampTypeDescription
uid*Chaîneun identifiant unique interne pour le type d’événement.
type*Chaînele type de composant. Doit correspondre à app-event.
name*Chaînele libellé affiché dans HubSpot (50 caractères maximum). Cette valeur ne peut pas être mise à jour après la création.
objectType*Chaînele nom complet du type d’objet CRM auquel les occurrences d’événements peuvent être associées. Cette valeur ne peut pas être modifiée après la création. Peut être l’un des éléments suivants : COMPANY, CONTACT, CUSTOM_OBJECT, DEAL, TICKET, APP_OBJECT.
headerTemplateChaînele modèle de rendu de l’en-tête de la carte d’activité CRM chronologie. Peut contenir jusqu’à 1 000 caractères.
detailTemplateChaînele modèle de rendu pour le corps de la carte d’activité CRM chronologie. Peut contenir jusqu’à 10 000 caractères.
propertiesTableaupropriétés définies pour le type d’événement dans lequel vous stockerez les données d’occurrence d’événement. Chaque type d’événement peut avoir jusqu’à 500 propriétés. Découvrez-en davantage sur les propriétés d’événement ci-dessous.

​
Propriétés d’événement

Lors de la définition du schéma d’événement, utilisez le tableau properties pour définir les champs vers lesquels vous enverrez les données d’occurrence d’événement. Chaque type d’événement peut avoir jusqu’à 500 propriétés. 
 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]

Les champs marqués par * sont requis.

ChampTypeDescription
name*Chaînele nom interne de la propriété. Doit être en minuscules et comporter entre 1 et 500 caractères. Les noms de propriété doivent être uniques par type d’événement. Cette valeur ne peut pas correspondre à la regex "[A-Za-z0-9_\\-.]+" ou commencer par hs_.
label*Chaînele libellé affiché dans HubSpot. Doit être en minuscules et comporter entre 1 et 500 caractères.
type*Chaînele type de données capturées dans la propriété. Peut être l’un des éléments suivants STRING, NUMBER, DATE, ENUMERATION.
optionsTableaupour les propriétés de type ENUMERATION, ce champ fournit les options disponibles. Doit contenir au moins une option. Chaque option est un objet qui contient :
  • name : le libellé de l’option affichée dans HubSpot.
  • value : la valeur interne fournie par l’occurrence de l’événement.
Le name et le label doivent être uniques dans le type d’événement.
objectPropertyNameChaînele cas échéant, le nom de la propriété d’objet CRM qui doit être mise à jour lorsque des données d’événement sont envoyées à HubSpot. La valeur de cette propriété remplacera toutes les valeurs existantes dans cette propriété. Découvrez-en davantage sur l’horodatage des propriétés des fiches d’informations CRM ci-dessous.

​
Horodatage de propriété

Dans certains cas, vous souhaiterez peut-être modifier les valeurs des propriétés de la fiche d’informations CRM en fonction des données d’occurrence d’événement de l’application. Par exemple, vous pouvez vouloir mettre à jour le prénom et le nom de famille d’un contact avec de nouvelles valeurs définies par l’occurrence (par exemple, soumission de formulaire). Pour mettre à jour les propriétés des fiches d’informations CRM via des occurrences d’événement, vous pouvez lier une propriété d’événement à une propriété CRM dans le schéma de type d’événement. Dans les champs de définition d’une propriété d’événement donnée, incluez le champ objectPropertyName et précisez la propriété CRM à associer. Une fois qu’une propriété est liée, HubSpot mettra toujours à jour la valeur de la propriété sur la fiche d’informations CRM en utilisant la valeur de l’occurence la plus récente en fonction du champ timestamp. Par exemple, le schéma de type d’événement ci-dessous associe la propriété d’événement customerName à une propriété de contact personnalisée nommée custom_property_name. Lorsque les données d’occurrence d’événement incluent une valeur pour customerName, custom_property_name sera mise à jour pour la fiche d’informations CRM associée. 
 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string",
       "objectPropertyName": "custom_property_name"
     }
   ]

​
Modèles de rendu

Les schémas de type d’événement peuvent inclure les champs headerTemplate et detailTemplate pour configurer le rendu des occurrences d’événement sur les chronologies des fiches d’informations CRM.
  • headerTemplate : une description d’une ligne de l’événement en haut de la carte d’activité (jusqu’à 1 000 caractères).
  • detailTemplate : les détails de l’événement dans le corps de la carte d’activité (jusqu’à 10 000 caractères).
Les modèles de rendu sont écrits à l’aide de Markdown avec les modèles Handlebars. Ces modèles peuvent restituer les données d’occurrence d’événement comme suit :
  • Dans les deux modèles, vous pouvez accéder à toutes données de property transmises par l’occurrence d’événement à l’aide de la syntaxe {{propertyName}}.
  • Dans le detailTemplate, vous pouvez également accéder aux valeurs extraData transmises par l’occurrence d’événement à l’aide de la syntaxe {{extraData.fieldName}}. Vous pouvez accéder à n’importe quel niveau d’attribut en notation par points extraData, tel que {{extraData.person1.preferredName}}.
L’objet extraData peut seulement contenir un JSON valide. Si le JSON est erroné, l’occurrence sera rejetée et vous recevrez une réponse d’erreur.
Par exemple, les modèles ci-dessous utilisent les données de propriété customerName et loginLocation, ainsi que le champ surveyData de extraData envoyé via l’occurrence d’événement. Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact. 
"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",
Les modèles étant conçus avec Markdown et Handlebars, vous pouvez tirer parti des aides de Handlebars pour rendre le contenu plus dynamique. Par exemple, l’élément suivant detailTemplate inclut l’assistant #if pour effectuer une restitution conditionnelle du contenu selon que les données d’occurrence d’événement incluent ou non le champ surveyData dans extraData.
  • Si extraData contient surveyData, afficher les réponses à l’enquête après connexion.
  • En l’absence de surveyData lors de l’occurrence de l’événement, afficher No additional information..
Capture d'écran montrant l'affichage de l'exemple de code ci-dessous sur la chronologie d'un contact. 
"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."

​
Utilisation d’iframes

Lorsque les données d’occurrence d’événement contiennent le champ timelineIFrame, la carte d’activité de la chronologie inclura un lien hypertexte sur lequel les utilisateurs pourront cliquer pour ouvrir le contenu lié dans un iframe. Capture d'écran d'un lien inclus dans une carte d'activité de chronologie en raison du champ timelineIFrame 
"timelineIFrame": {
    "linkLabel": "Click me",
    "headerLabel": "This is an iframe",
    "url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
    "width": 300,
    "height": 300
  }
ChampTypeDescription
linkLabelChaînele texte du lien hypertexte qui lancera l’iframe au clic.
headerLabelChaînele libellé de la fenêtre modale qui affiche le contenu iFrame.
urlChaînel’URL du contenu de l’iframe.
widthEntierla largeur de la fenêtre modale de l’iframe.
heightEntierla hauteur de la fenêtre modale de l’iframe.

​
Occurrence de l’événement

Pour envoyer des occurrences d’événements pour un type d’événement donné, effectuez une requête POST aux points de terminaison ci-dessous. L’API d’événements d’application comprend des points de terminaison pour l’envoi d’occurrences d’événements uniques et de lots d’occurrences de plusieurs événements. Pour les deux points de terminaison, les données d’occurrence d’événement devront être validées par rapport à un schéma de type d’événement existant, que vous indiquerez eventTypeName dans le corps de la requête.
Pour envoyer une occurrence d’événement unique, effectuez une requête POST à /integrators/timeline/v4/events.Dans le corps de la requête, incluez les données d’occurrence d’événement, en respectant le schéma défini du type d’événement.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},
Dans le corps de la requête, incluez les données basées sur le schéma de type d’événement défini. Le corps de la requête doit inclure l’événement eventTypeName, que vous pouvez récupérer via l’API. 
  {
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "8675309",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  },
  "id": "login-1529a3gda23",
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer":"Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer":"Extremely likely"
      }
    ]
  }
}

Les champs marqués par * sont requis.

ChampTypeDescription
eventTypeName*Chaînele nom entièrement qualifié du type d’événement, que vous utiliserez pour identifier l’événement via l’API. Cette valeur est automatiquement définie par HubSpot et peut être obtenue via l’API après la création du type d’événement. Cette valeur ne peut pas être modifiée après la création.
objectId*Chaînel’ID de la fiche d’informations de CRM à associer à l’événement. Ce champ peut être utilisé pour tous les types de fiches d’informations de CRM et constitue l’identifiant recommandé. Découvrez-en davantage sur l’association des fiches d’informations CRM.
emailChaînepour l’association de contact, vous pouvez fournir l’adresse e-mail du contact à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
utkChaînepour l’association de contacts, vous pouvez fournir le jeton utilisateur d’un contact existant à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
domainChaînepour l’association d’entreprise, vous pouvez fournir le domaine de site web d’une entreprise existante. Découvrez-en davantage sur l’association des fiches d’informations CRM.
timestampChaînedéfinit l’heure de l’occurrence de l’événement (format ISO 8601). Si ce champ n’est pas renseigné, HubSpot utilisera par défaut l’horodatage de l’envoi des données d’occurrence d’événement.
propertiesObjetpaires clé-valeur des noms et valeurs des propriétés que vous avez définies pour le type d’événement.
extraDataTableaulorsqu’il est inclus, fournit des informations supplémentaires pour le rendu de la chronologie. Doit être un JSON valide. Découvrez-en davantage sur les données supplémentaires dans le rendu des modèles.
timelineIFrameObjetune fois incluse, la carte de chronologie comprendra un lien hypertexte qui permet aux utilisateurs d’ouvrir le contenu lié dans un iframe. Découvrez-en davantage sur l’utilisation des iframes.
idChaîneun identifiant unique pour l’occurrence de l’événement. Doit être unique dans le type d’événement. Si ce champ n’est pas renseigné, HubSpot générera un GUID aléatoire. Lorsque plusieurs événements ont le même ID, le premier sera accepté et tous les autres seront rejetés.
Si certaines occurrences ne sont pas validées, les occurrences validées avec succès seront toujours acceptées et persistées. Le message d’erreur dans la réponse fournira des informations sur ce que vous devrez corriger. Capture d'écran d'un exemple de message d'erreur que vous pouvez recevoir lors de l'envoi de données d'occurrence d'événement

​
Association des fiches d’informations CRM

Chaque événement doit être associé à une fiche d’informations CRM, le type d’objet CRM étant défini par le schéma de type d’événement. L’API des événements de l’application comprend plusieurs champs pour associer les données d’occurrence d’événement aux fiches d’informations CRM. Pour tous les objets CRM pris en charge, il est recommandé d’utiliser le champ objectId. Cependant, dans certaines situations, vous souhaiterez peut-être utiliser les autres champs.
  • utk/email : si vous ne connaissez pas l’ID du contact, utilisez le champ utk et/ou email pour l’identification. Fournir ces deux identifiants vous permet également de créer et de mettre à jour des contacts. Par exemple :
    • Si utk correspond à un contact existant mais que l’email ne correspond pas, HubSpot mettra à jour le contact avec la nouvelle adresse e-mail.
    • Si aucun objectId n’est fourni, l’occurrence de l’événement sera associée à un contact existant correspondant à utk/email, ou HubSpot créera un nouveau contact si aucune correspondance n’est trouvée.
    • Notez que le utk seul ne peut pas créer de nouveaux contacts. Vous devez toujours inclure l’email avec utk pour garantir une bonne association.
  • domain : pour l’association d’entreprises, vous devez fournir l’objectId, mais vous pouvez également l’inclure le domain pour mettre à jour la propriété de domain de cette entreprise.