Dernière modification : 22 août 2025
Les événements personnalisés vous permettent de définir et de suivre des événements propres à votre entreprise, tels que des événements sur votre site ou dans une application. Vous pouvez configurer des événements pour stocker des informations au sein des propriétés, que vous pouvez ensuite utiliser dans l’ensemble des outils de HubSpot. Pour envoyer des données d’événement personnalisé à HubSpot, vous devez d’abord configurer l’événement. Ceci est similaire aux objets CRM personnalisés, pour lesquels vous devez d’abord définir l’objet personnalisé avant de pouvoir créer des fiches d’informations individuelles pour cet objet. La définition d’un événement comprend des détails tels que ses métadonnées, ses associations d’objets CRM et ses propriétés. Vous trouverez ci-dessous des informations sur la création et la gestion de définitions d’événements à l’aide de l’API. Pour découvrir comment créer des définitions d’événements sans utiliser l’API, consultez la base de connaissances de HubSpot.

​
Créer une définition d’événement

Pour créer le schéma d’événement personnalisé, effectuez une requête POST à events/v3/event-definitions. Dans le corps de la requête, incluez les définitions de votre schéma d’événement, y compris son libellé, son nom, ses associations d’objets CRM et ses propriétés personnalisées. Le corps de la requête ci-dessous fournit un exemple basique de définition d’événement : 
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}
Si vous souhaitez lier automatiquement les finalisations d’événements aux fiches d’informations d’un type d’objet CRM spécifique, vous pouvez inclure un customMatchingId dans votre requête POST. Dans ce champ, définissez un objet primaryObjectRule avec deux champs : la propriété d’objet unique que vous avez préalablement configurée comme targetObjectPropertyName, et l’une des propriétés que vous avez définies dans les propertyDefinitions de votre définition d’événement. Par exemple, le corps de la requête suivante spécifie une customMatchingId qui correspond à un nom de propriété d’objet CRM de "unique_object_property" et à un nom de propriété d’événement de "string_property" : 
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}
Une liste complète des paramètres disponibles pour le corps de la requête est détaillée dans le tableau ci-dessous :
ParamètreTypeDescription
labelChaîneLe libellé compréhensible de l’événement, qui s’affichera dans HubSpot (jusqu’à 100 caractères). Les longs libellés peuvent être coupés dans certaines parties de l’interface utilisateur de HubSpot.
nameChaîneLe nom interne unique de l’événement, que vous utiliserez pour référencer l’événement via l’API. Si aucune valeur n’est fournie, HubSpot en générera automatiquement une basée sur le libellé.
  • Cette propriété ne peut pas être modifiée après la création de la définition d’événement.
  • Cette propriété ne peut contenir que des lettres minuscules, des chiffres, des tirets bas et des traits d’union (jusqu’à 50 caractères).
  • Le premier caractère doit être une lettre.
descriptionChaîneLa description de l’événement, qui s’affichera dans HubSpot.
primaryObjectChaîneLe type d’objet CRM auquel les données d’événement seront associées. Les événements terminés apparaîtront sur les enregistrements CRM de ce type d’objet. Peut être l’un des suivants : "CONTACT" (par défaut), "COMPANY", "DEAL", "TICKET", "<CUSTOM_OBJECT_NAME>". Ce type d’objet ne peut pas être modifié après la création de la définition de l’événement.
propertyDefinitionsTableauEn plus des propriétés d’événement par défaut de HubSpot, vous pouvez inclure ce tableau pour définir événement personnalisé propriétés (jusqu’à 50). Pour chaque objet de propriété, incluez les champs suivants :
  • name : le nom interne de la propriété, que vous utiliserez lors de l’envoi de données d’événement via l’API.
  • label : le libellé dans l’application de la propriété.
  • type : le type de la propriété. La valeur par défaut est string.
  • options : pour les propriétés de type enumeration, ce tableau définit les valeurs disponibles. Doit inclure à la fois un label et une value pour chaque option.
  • description : texte décrivant la propriété.
customMatchingIdObjetAu lieu d’inclure le objectId de l’objet cible dans les données de finalisation d’événement, ce champ facultatif définit une règle pour lier automatiquement les achèvements d’événement aux fiches d’informations du type d’objet CRM spécifié. Pour ce faire, faites correspondre la valeur d’une propriété dans les données d’événement avec la valeur d’une propriété unique sur l’objet cible. Cet objet doit inclure un objet primaryObjectRule imbriqué, qui à son tour doit inclure deux champs :
  • targetObjectPropertyName : une chaîne qui spécifie le nom de la propriété unique sur l’objet CRM cible à utiliser pour la correspondance.
  • eventPropertyName : une chaîne qui spécifie le nom de la propriété dans les données de l’événement personnalisé à utiliser pour la correspondance.
includeDefaultPropertiesBooléenChamp facultatif qui indique si l’événement doit inclure l’ensemble des propriétés d’événement par défaut. Si aucune valeur n’est fournie, ce champ sera automatiquement défini sur true.

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

Les propriétés des événements personnalisés sont utilisées pour stocker des informations sur l’achèvement de chaque événement personnalisé. Ces propriétés doivent être utilisées le cas échéant pour l’envoi d’achèvements d’événements, mais elles ne sont pas nécessaires pour qu’un achèvement d’événement soit valide. Pour chaque définition d’événement, HubSpot fournit un ensemble de 32 propriétés par défaut. En outre, vous pouvez créer jusqu’à 50 propriétés personnalisées par définition d’événement. Les propriétés peuvent être des types suivants :
  • bool : une propriété qui reçoit une valeur booléenne. Les valeurs doivent être représentées par true ou false.
  • date : une propriété qui reçoit une date représentant un jour, un mois et une année spécifiques. Les valeurs doivent être représentées au format UTC et peuvent être formatées sous forme de chaînes ISO 8601 ou d’horodatages EPOCH en millisecondes (c.-à-d. minuit UTC).
  • datetime : une propriété avec des valeurs epoch (en millisecondes) ou ISO8601 représentant un horodatage.
  • enumeration : une propriété avec des options prédéfinies. Lors de la création de ce type de propriété, incluez un tableau options pour définir les valeurs disponibles.
  • number : une propriété qui reçoit des valeurs numériques avec un maximum d’une décimale.
  • string : une propriété qui reçoit des chaînes de texte en clair. Si le nom de la propriété contient les mots url, referrer ou link, la valeur de la propriété peut comporter jusqu’à 1 024 caractères. Autrement, les valeurs des propriétés peuvent comporter jusqu’à 256 caractères.
Ci-dessous, vous découvrirez les propriétés des événements par défaut de HubSpot, comment définir de nouvelles propriétés pour les événements existants et comment mettre à jour les propriétés des événements personnalisés existants.

​
Propriétés d’événement par défaut de HubSpot

  • hs_asset_description
  • hs_asset_type
  • hs_browser
  • hs_campaign_id
  • hs_city
  • hs_country
  • hs_device_name
  • hs_device_type
  • hs_element_class
  • hs_element_id
  • hs_element_text
  • hs_language
  • hs_link_href
  • hs_operating_system
  • hs_operating_version
  • hs_page_content_type
  • hs_page_id
  • hs_page_title
  • hs_page_url
  • hs_parent_module_id
  • hs_referrer
  • hs_region
  • hs_screen_height
  • hs_screen_width
  • hs_touchpoint_source
  • hs_tracking_name
  • hs_user_agent
  • hs_utm_campaign
  • hs_utm_content
  • hs_utm_medium
  • hs_utm_source
  • hs_utm_term

​
Définir de nouvelles propriétés

Pour définir une nouvelle propriété sur un événement personnalisé existant, effectuez une requête POST à events/v3/event-definitions/{eventName}/property. Dans le corps de la requête, incluez la définition de votre propriété. 
{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}
Lorsque vous donnez un nom à votre propriété, gardez à l’esprit les éléments suivants :
  • Une fois que vous avez créé une propriété, son nom ne peut plus être modifié.
  • Le nom ne peut contenir que des lettres minuscules, des chiffres, des tirets bas et des tirets.
  • Le premier caractère du nom de la propriété doit être une lettre.
  • Le nom de la propriété et le libellé peuvent comporter chacun jusqu’à 50 caractères.
  • Si aucun nom de propriété n’est fourni, un nom sera généré automatiquement en utilisant le libellé de la propriété.
  • Les longs libellés peuvent être coupés dans certaines parties de l’interface utilisateur de HubSpot.

​
Mise à jour des propriétés personnalisées existantes

Pour mettre à jour une propriété existante sur un événement personnalisé, effectuez une requête PATCH à events/v3/event-definitions/{eventName}/property. Les seuls champs qui peuvent être mis à jour sur une propriété sont les champs label, description, et options pour les propriétés d’énumération.

​
Remarque :

Pour modifier le type de propriété, utilisez le point de terminaison DELETE pour supprimer la propriété et la recréer avec le bon type.

​
Supprimer une propriété

Pour supprimer une propriété existante sur un événement personnalisé, effectuez une requête DELETE à events/v3/event-definitions/{eventName}/property/{propertyName}. Lorsqu’une propriété est supprimée, elle ne pourra plus être utilisée dans le cadre d’événements futurs. Les achèvements antérieurs conservent leurs valeurs de propriété.

​
Mise à jour d’un événement

Pour mettre à jour un schéma d’événement personnalisé existant, effectuez une requête PATCH à events/v3/event-definitions/{eventName}. Les seuls champs de définition d’événement qui peuvent être mis à jour sont label et description. 
{
  "label": "Event label",
  "description": "A description of the event"
}

​
Supprimer un événement

Pour supprimer un événement personnalisé, effectuez une requête DELETE à events/v3/event-definitions/{eventName}. La suppression d’un événement personnalisé entraînera sa suppression de tous les autres outils HubSpot qui le référencent, tels que les workflows et les rapports.

​
Remarque : Lors de la suppression d’un événement :

  1. Tous les événements correspondant à cette définition d’événement seront supprimés et irrécupérables.
  2. Les éléments eventName précédemment supprimés ne peuvent pas être réutilisés. Soyez donc prudent lors de la suppression d’un événement.

​
Obtenir des définitions d’événements existants

Pour récupérer une seule définition d’événement, effectuez une requête GET à events/v3/event-definitions/{eventName}. Pour rechercher des définitions d’événements selon des critères spécifiques, effectuez une requête GET à events/v3/event-definitions. Vous pouvez fournir les paramètres de requête suivants pour affiner votre recherche :
  • searchString : recherche les événements qui contiennent les caractères spécifiés dans le champ name. La recherche n’est pas floue, mais il s’agit plutôt d’une recherche naïve de type contains.
  • after : une chaîne de caractères hachée fournie dans les réponses paginées pour afficher la page suivante des résultats de la recherche.
  • limit : le nombre maximum de résultats à renvoyer.
  • includeProperties : une valeur booléenne qui spécifie si les propriétés de l’événement doivent être incluses dans les résultats renvoyés.