Envoyer les événements personnalisés terminés

Produits pris en charge

Exige l'un des produits suivants ou un produit supérieur.

Marketing HubEntreprise

Sales HubEntreprise

Service HubEntreprise

Content HubEntreprise

Dernière modification : 22 août 2025

Les événements personnalisés sont des événements définis par le compte qui stockent les détails de l’événement dans des propriétés d’événement. Outre la personnalisation de votre code de suivi pour envoyer des données d’événement à HubSpot, vous pouvez également envoyer des données de fin d’événement via cette API. Découvrez ci-dessous comment utiliser l’API pour créer des événements personnalisés et envoyer/récupérer des données d’événements personnalisés.

Définir l’événement

Pour envoyer des données d’événements terminés à HubSpot, vous devez d’abord définir l’événement lui-même, y compris ses métadonnées, ses associations d’objets CRM et ses propriétés. Vous pouvez définir des événements en utilisant l’API de définition d’événement personnalisée, ou si vous disposez d’un abonnement au Marketing Hub Entreprise, vous pouvez créer l’événement dans HubSpot. Lors de la création de l’événement, HubSpot fournit l’option d’inclure un ensemble de propriétés d’événement par défaut que vous pourrez utiliser pour stocker des données d’événement. Vous pouvez également créer des propriétés supplémentaires pour l’événement. Ces propriétés peuvent être créées ou modifiées à tout moment. Une fois votre événement configuré, vous pouvez lui envoyer des données via l’API ou en personnalisant votre code de suivi HubSpot.

Envoyer des données d’événements

Pour envoyer des données d’événement à HubSpot, effectuez une requête POST à https://api.hubspot.com/events/v3/send avec vos données d’événement dans le corps de la requête. Avant d’envoyer des données d’événement, vérifiez les limites ci-dessous, car le dépassement de ces limites entraînera une erreur.

{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}

Paramètre	Type	Description
`eventName`	Chaîne	Le nom interne de l’événement. Vous pouvez le trouver en interrogeant vos définitions d’événements existantes ou dans l’application HubSpot.
`objectId`	Chaîne	L’ID de la fiche d’informations du CRM auquel l’événement sera associé. Pour les contacts, vous pouvez également utiliser le champ `email` ou `utk` pour identifier le contact par adresse e-mail ou par un jeton d’utilisateur HubSpot. Tous les autres types d’objets exigent `objectId`, sauf si un ID de correspondance personnalisé est défini pour l’événement. Si un `customMatchingId` est défini pour l’événement, HubSpot définira ou remplacera automatiquement `objectId` en fonction du mappage configuré. Découvrez-en davantage dans le guide des définitions d’événements personnalisés.
`occurredAt`	Chaîne	Par défaut, HubSpot définit l’horodatage d’événements terminés à l’heure d’envoi de la demande. Pour spécifier l’heure de fin de l’événement, incluez un horodatage dans un champ `occurredAt` du corps de la requête `POST` (format ISO 8601). Cela peut être particulièrement utile pour antidater les données d’événements afin de refléter plus précisément les événements terminés réels.
`properties`	Objet	Les propriétés d’événement auxquelles envoyer des données. Cela peut inclure les propriétés d’événement par défaut de HubSpot ou toute autre propriété personnalisée que vous avez définie pour l’événement. La plupart des propriétés d’événement par défaut sont des propriétés de chaîne, mais vous pouvez vérifier toutes les propriétés d’événements en interrogeant la définition de l’événement ou en accédant à l’événement dans HubSpot. Si un ID de correspondance personnalisé est configuré pour l’événement, vous pouvez omettre `objectId`. HubSpot tentera de lier l’événement à un objet CRM en définissant `objectId` sur l’événement en fonction du mappage configuré. Découvrez-en davantage sur les propriétés d’événement ci-dessous.

Remarque :

Le dépassement de l’une des limites suivantes entraînera l’échec de la demande :

Le libellé de la propriété et le nom interne sont limités à 50 caractères.
Les propriétés d’URL et de référent peuvent contenir jusqu’à 1 024 caractères, tandis que toutes les autres propriétés peuvent contenir jusqu’à 256 caractères.
Chaque événement peut contenir des données pour un maximum de 50 propriétés.
Les noms internes des propriétés doivent commencer par une lettre et ne contenir que des lettres minuscules de a à z, des chiffres de 0 à 9 et des tirets bas.
Les propriétés ayant le même nom interne après la mise en minuscule sont considérées comme des doublons, et une seule des propriétés sera utilisée à la fin du processus. HubSpot triera par ordre lexicographique croissant et conservera la dernière propriété vue parmi les 50 premières propriétés.
Le nombre de définitions d’événement unique est limité à 500 par compte.
Le nombre d’événements terminés est limité à 30 millions par mois.

Récupérer des données d’événements

Pour récupérer les données d’événement, effectuez une requête GET à /events/v3/events.

Pour renvoyer tous les événements terminés pour un événement spécifique, incluez le paramètre eventType ainsi que le nom interne de l’événement (par exemple, pe123456_custom_event). Vous pouvez récupérer tous les types d’événements via l’API d’analytics d’événements.
Pour renvoyer des événements terminés pour un objet spécifique, incluez le paramètre objectType ainsi que les paramètres objectId ou objectProperty.<property>. objectType Doit spécifier le type d’objet CRM (par ex., contact), tandis que les autres paramètres spécifient la valeur de l’identifiant unique pour l’objet (soit ID de fiche d’informations, soit une valeur de propriété d’identifiant unique). Pour les contacts, vous pouvez utiliser email comme propriété d’identifiant unique.

Par exemple, pour récupérer tous les événements terminés par un contact spécifique, l’URL de votre demande peut être : /events/v3/events?objectType=contact&objectId=111111. Vous pouvez également utiliser l’adresse e-mail du contact : /events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com Pour filtrer les résultats par événements terminés avec une valeur de propriété d’événement spécifique, vous pouvez inclure le paramètre property.<propertyName>. Par exemple, pour récupérer les événements de visite de page pour votre page d’accueil, l’URL de votre demande peut être : /events/v3/events?eventType=e_visited_page&property.hs_page_title=home

Pour propriété valeurs par des espaces, remplacez les espaces par %20 ou +. Par exemple : property.hs_page_title=home+page.

Découvrez-en davantage sur les paramètres disponibles dans la documentation de référence.

Propriétés d’événement

Les données d’achèvement d’événement sont stockées dans les propriétés d’événement, dans l’ensemble de propriétés d’événement par défaut ou dans propriétés personnalisées. Lors de l’envoi de données d’événement, incluez un objet properties avec des paires clé-valeur pour les propriétés que vous souhaitez mettre à jour ainsi que les valeurs de propriété à stocker.

"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }

Les valeurs que vous enverrez dépendront du type de propriété d’événement. La plupart des propriétés d’événements par défaut sont des textes à une ligne (chaîne). Toutefois, vous pouvez créer des propriétés personnalisées de tout type pour chaque événement. Passez en revue le tableau ci-dessous lors du formatage de valeurs de propriétés.

Type de propriété	Description
`bool`	Une valeur booléenne, soit `true` ou `false`.
`enumeration`	Une chaîne représentant un ensemble d’options. Lorsque vous envoyez plusieurs valeurs, séparez-les par un point-virgule. Dans HubSpot, ce type correspond aux propriétés de menu déroulant, de case d’option et de plusieurs cases à cocher.
`date`	Une valeur 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`	Un horodatage représentant un jour, un mois, une année et une heure 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 UNIX en millisecondes.
`number`	Une valeur numérique contenant des chiffres et au maximum une décimale. Dans HubSpot, ce type correspond aux propriétés calculées et aux propriétés de nombre.
`string`	Une chaîne de texte brut limitée à 65 536 caractères. Dans HubSpot, ce type correspond aux propriétés de texte à une ligne et à plusieurs lignes.

Pour afficher les propriétés disponibles d’un événement :

Dans votre compte HubSpot, accédez à Gestion des données > Événement personnalisé.
Dans le tableau, cliquez sur le nom du CTA.
En haut, cliquez sur l’onglet Propriétés.
Dans le tableau des propriétés, affichez le type de propriété sous le nom de la propriété.

Rapport d’attribution

Les événements JavaScript tels que les événements d’élément cliqué et d’URL visitée sont automatiquement renseignés avec le type d’élément et les données d’interaction pour les rapports d’attribution. Pour inclure les mêmes données pour les événements suivis manuellement, vous devrez inclure manuellement les données dans le corps de la requête en utilisant les propriétés d’événement. En savoir plus sur l’analyse des événements personnalisés. Découvrez ci-dessous les valeurs disponibles pour les types de ressources et les sources d’interaction, ainsi que des exemples de requêtes.

Type d’élément

Pour attribuer un type de ressource spécifique à une requête d’événement comportemental personnalisé, incluez la propriété hs_page_content_type dans le corps de la requête. Par exemple :

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Vous pouvez également utiliser la propriété hs_asset_type. Si hs_page_content_type et hs_asset_type sont tous les deux inclus dans une seule requête, hs_page_content_type remplacera la valeur hs_asset_type.

Les types de contenu standard de HubSpot, tels que les pages de destination et les articles de blog, peuvent être représentés avec les valeurs suivantes :

Valeur	Description
`STANDARD_PAGE`	Une interaction avec une page de site web.
`LANDING_PAGE`	Une interaction avec une page de destination.
`BLOG_POST`	Une interaction avec un article de blog.
`KNOWLEDGE_ARTICLE`	Une interaction avec un article de la base de connaissances.

Pour tous les autres types de ressources, utilisez les valeurs suivantes :

Valeur	Description
`AD`	Une interaction avec une publicité, telle qu’une publicité Facebook ou Google.
`CALL`	Une interaction avec un appel.
`CONTACT_IMPORT`	Une interaction via un import de contact
`CONVERSATION`	Une interaction liée à une conversation HubSpot.
`CUSTOM_BEHAVIORAL_EVENT_NAME`	Le nom interne d’un événement personnalisé, comme `pe123456_manually_tracked_event`.
`EMAIL`	Une interaction avec un e-mail.
`EXTERNAL_PAGE`	Une interaction avec une page externe.
`INTEGRATIONS`	Une interaction via une intégration.
`MARKETING_EVENT`	Une interaction avec un événement marketing.
`MEDIA_BRIDGE`	Une interaction via la passerelle multimédia.
`MEETING`	Une interaction avec une réunion.
`SALES_EMAIL`	Une interaction avec un e-mail de vente individuel.
`SEQUENCE`	Une interaction avec une séquence.
`SOCIAL_POST`	Une interaction avec un post sur les réseaux sociaux.
`OTHER`	Une interaction avec une ressource n’appartenant à aucune des catégories ci-dessus.

Titre de ressource

Pour attribuer un événement personnalisé à une ressource, incluez la propriété hs_page_title ou hs_asset_title dans votre requête, avec le nom de la ressource formaté sous forme de chaîne. Par exemple : hs_page_title:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Sources d’interaction

Pour attribuer un événement comportemental personnalisé à une source spécifique, incluez la propriété hs_touchpoint_source dans votre requête avec l’une des valeurs suivantes :

Valeur	Description
`CONVERSATION`	La source d’interaction est une conversation.
`DIRECT_TRAFFIC`	La source d’interaction est du trafic direct.
`EMAIL_MARKETING`	La source d’interaction est un e-mail marketing.
`HUBSPOT_CRM`	La source d’interaction est le CRM de HubSpot.
`INTEGRATION`	La source d’interaction est une intégration.
`MARKETING_EVENT`	La source d’interaction est un événement marketing.
`OFFLINE`	La source d’interaction est hors ligne.
`ORGANIC_SEARCH`	La source d’interaction est une recherche naturelle.
`OTHER_CAMPAIGNS`	La source d’interaction provient d’une campagne sans catégorie.
`PAID_SEARCH`	La source d’interaction est une publicité payante sur les moteurs de recherche.
`PAID_SOCIAL`	La source d’interaction est une publicité de réseaux sociaux payante.
`REFERRALS`	La source d’interaction est un renvoi.
`SALES`	La source d’interaction est les ventes.
`SOCIAL_MEDIA`	La source d’interaction est les réseaux sociaux (pas une publicité de réseaux sociaux payante).

Événements

Définitions d'événements

Événements terminés

Envoyer les événements personnalisés terminés

Définir l’événement

Envoyer des données d’événements

Remarque :

Récupérer des données d’événements

Propriétés d’événement

Rapport d’attribution

Type d’élément

Titre de ressource

Sources d’interaction

Événements

Définitions d'événements

Événements terminés

​Définir l’événement

​Envoyer des données d’événements

​Remarque :

​Récupérer des données d’événements

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

​Rapport d’attribution

​Type d’élément

​Titre de ressource

​Sources d’interaction

Définir l’événement

Envoyer des données d’événements

Remarque :

Récupérer des données d’événements

Propriétés d’événement

Rapport d’attribution

Type d’élément

Titre de ressource

Sources d’interaction