Webhooks
L'API Webhooks vous permet de vous abonner à des événements qui se produisent dans un compte HubSpot sur lequel est installée votre intégration. Plutôt que de passer un appel d'API lorsqu'un événement se produit dans un compte connecté, HubSpot peut envoyer une demande HTTP à un point de terminaison que vous configurez. Vous pouvez configurer des événements abonnés dans les paramètres de votre application ou à l'aide des points de terminaison ci-dessous. Les webhooks peuvent être plus évolutifs que des sondages réguliers concernant des modifications, notamment pour les applications massivement installées.
L'utilisation de l'API Webhooks nécessite les éléments suivants :
- Vous devez configurer une application HubSpot pour utiliser les webhooks en vous abonnant aux événements pour lesquels vous souhaitez recevoir des notifications et en précisant une URL pour l'envoi de celles-ci. Consultez la documentation relative aux prérequis pour en savoir plus sur la création d'une application.
- Vous devez déployer un point de terminaison publiquement accessible et sécurisé (HTTPS) pour cette URL, capable de gérer les charges utiles pertinentes du webhook spécifiées dans cette documentation.
Les webhooks sont configurés pour une application HubSpot, et non pour des comptes individuels. Tous les comptes qui installent votre application (par le biais du flux OAuth) seront abonnés à ses abonnements de webhook.
Vous pouvez vous abonner à des événements d'objet CRM, qui comprennent des contacts, des entreprises, des transactions, des tickets, des produits et des lignes de produit ainsi qu'à des événements de conversations.
Please note: to subscribe to conversations webhooks, you need access to the conversations inbox and messages APIs, which is currently in beta.
Pour utiliser les webhooks afin de vous abonner à des événements CRM, votre application devra être configurée pour exiger le domaine crm.objects.contacts.read. Votre application devra être configurée pour exiger le domaine conversations.read pour vous abonner aux événements de conversations.
Vous devez configurer ces domaines avant de créer un abonnement de webhook. Consultez la documentation OAuth pour plus de détails sur les domaines et la configuration de l'URL d'autorisation pour votre application.
Si votre application utilise déjà des webhooks, vous ne pourrez pas supprimer le domaine crm.objects.contacts.read ou conversations.read tant que vous ne supprimerez pas tous les abonnements de webhook de votre application.
Avant de configurer des abonnements de webhook, vous devez spécifier une URL à laquelle envoyer ces notifications. Vous pouvez également ajuster la limitation d'événement, qui correspond au nombre de requêtes simultanées que votre point de terminaison peut gérer.
Cette limitation est une limite de concomitance. Dès qu'une réponse à une demande est fournie, le total des demandes actives sera réduit et une autre demande pourra être envoyée. Par exemple, si vous avez une limite d'une requête par tranche de 10 secondes, si une requête est envoyée, HubSpot attendra qu'une réponse arrive ou que 10 secondes s'écoulent avant d'envoyer une autre requête, selon la première éventualité.
La définition de cette limite permet d'envoyer des notifications aussi vite que possible, sans trop surcharger votre API.
- Si vous définissez une limite trop basse, il est possible que les notifications expirent si trop de notifications sont envoyées à votre API et que cette limite soit saturée pendant plusieurs secondes. Cela entraînera des retards de notification.
- Si vous définissez une limite trop élevée, il est possible que vous saturiez les ressources disponibles à votre point de terminaison, ce qui pourrait entraîner des réponses lentes, des retards de notification ou une absence de réponse de votre point de terminaison.
Vous pouvez gérer vos paramètres d'URL et de limitation d'événement via la page de configuration de votre application dans votre compte de développeur :
- Dans votre compte de développeur, accédez à votre tableau de bord Applications.
- Cliquez sur le nom de l'application pour laquelle vous souhaitez configurer des webhooks.
- Dans le menu latéral de gauche, accédez à Webhooks.
- Dans le champ URL cible, saisissez l'URL vers laquelle HubSpot effectuera une demande POST pour le déclenchement des événements.
- Utilisez le paramètre Limitation d'événement pour ajuster le nombre maximal d'événements que HubSpot essaiera d'envoyer.
- Cliquez sur Enregistrer.
Vous pouvez utiliser les points de terminaison suivants et votre clé d'API de développeur pour configurer de façon programmée les paramètres de webhook pour une application.
Pour afficher tous les paramètres de webhook actuellement configurés pour une application, effectuez une demande GET à webhooks/v3/{appId}/settings.
Vous devrez inclure l'ID de l'application dans la demande, que vous trouverez sous le nom de l'application dans votre tableau de bord Applications ou dans l'onglet OAuth dans les paramètres de votre application.
Les paramètres contiennent les champs suivants :
| Champ | Description |
|---|---|
webhookUrl
| L'URL à laquelle HubSpot enverra des notifications de webhook. Elle doit être sur un serveur HTTPS. |
maxConcurrentRequests
| La limite de concomitance pour l'URL du webhook. Cette valeur doit être un nombre supérieur à cinq. |
Pour apporter des modifications à ces paramètres, effectuez une demande PUT à webhooks/v3/{appId}/settings et incluez les champs suivants dans le corps de la demande :
| Champ | Description |
|---|---|
targetUrl
| L'URL publique pour que HubSpot appelle l'endroit où les charges utiles de l'événement seront livrées. |
throttling
| Configurez les détails de limitation du webhook dans cet objet. L'objet de limitation comprend les champs |
period
| Échelle de temps pour ce paramètre. Peut être |
maxConcurrentRequests
| Le nombre maximal de demandes HTTP que HubSpot tentera d'effectuer vers votre application dans une période donnée en fonction de |
Par exemple, votre demande peut ressembler à ce qui suit :
Une fois que vous avez configuré l'URL de votre webhook et les limitations d'événement, vous devez créer un ou plusieurs abonnements. Les abonnements de webhook indiquent à HubSpot les événements que votre application spécifique souhaite recevoir.
Les abonnements s'appliquent à tous les clients qui ont installé votre intégration. Autrement dit, vous devez spécifier les abonnements dont vous avez besoin une seule fois. Une fois que vous avez activé un abonnement pour une application, il commencera automatiquement à obtenir les webhooks pour tous les clients qui ont installé votre application. Votre intégration commencera à recevoir les déclencheurs de webhook de tous les nouveaux clients.
Les types d'abonnement suivants sont pris en charge et peuvent être utilisés comme valeur pour le champ eventType lors de la création d'abonnements via l'API :
| Type d'abonnement | Domaine requis | Description |
|---|---|---|
contact.creation |
crm.objects.contacts.read |
Recevez une notification si un contact est créé dans le compte d'un client. |
contact.deletion |
Recevez une notification si un contact est supprimé dans le compte d'un client. | |
contact.merge |
Recevez une notification si un contact est fusionné avec un autre contact. | |
contact.associationChange |
Recevez une notification si un contact a une association ajoutée ou supprimée entre lui-même et un autre objet de webhook pris en charge (contact, entreprise, transaction, ticket, ligne ou produit ou produit). | |
contact.restore |
Recevez une notification si un contact est restauré à partir de la suppression. | |
contact.privacyDeletion |
Recevez une notification si un contact est supprimé pour des raisons de confidentialité. | |
contact.propertyChange |
Recevez une notification si une propriété spécifique est modifiée pour un contact dans le compte d'un client. | |
company.creation |
crm.objects.companies.read |
Recevez une notification si une entreprise est créée dans le compte d'un client. |
company.deletion |
Recevez une notification si une entreprise est supprimée dans le compte d'un client. | |
company.propertyChange |
Recevez une notification si une propriété spécifique est modifiée pour une entreprise dans le compte d'un client. | |
company.associationChange |
Recevez une notification si une entreprise a une association ajoutée ou supprimée entre elle-même et un autre objet de webhook pris en charge (contact, entreprise, transaction, ticket, ligne ou produit ou produit). | |
company.restore |
Recevez une notification si une entreprise est restaurée à partir de la suppression. | |
company.merge |
Recevez une notification si une entreprise est fusionnée avec une autre. | |
deal.creation |
crm.objects.deals.read |
Recevez une notification si une transaction est créée dans le compte d'un client. |
deal.deletion |
Recevez une notification si une transaction est supprimée dans le compte d'un client. | |
deal.associationChange |
Recevez une notification si une transaction a une association ajoutée ou supprimée entre elle-même et un autre objet de webhook pris en charge (contact, entreprise, transaction, ticket, ligne ou produit ou produit). | |
deal.restore |
Recevez une notification si une transaction est restaurée à partir de la suppression. | |
deal.merge |
Recevez une notification si une transaction est fusionnée avec une autre. | |
deal.propertyChange |
Recevez une notification si une propriété spécifique est modifiée pour une transaction dans le compte d'un client. | |
ticket.creation |
tickets |
Recevez une notification si un ticket est créé dans le compte d'un client. |
ticket.deletion |
Recevez une notification si un ticket est supprimé dans le compte d'un client. | |
ticket.propertyChange |
Recevez une notification si une propriété spécifique est modifiée pour un ticket dans le compte d'un client. | |
ticket.associationChange |
Recevez une notification si un ticket a une association ajoutée ou supprimée entre lui-même et un autre objet de webhook pris en charge (contact, entreprise, transaction, ticket, ligne ou produit ou produit). | |
ticket.restore |
Recevez une notification si un ticket est restauré à partir de la suppression. | |
ticket.merge |
Recevez une notification si un ticket est fusionné avec un autre. | |
product.creation |
e-commerce |
Recevez une notification si un produit est créé dans le compte d'un client. |
product.deletion |
Recevez une notification si un produit est supprimé dans le compte d'un client. | |
product.restore |
Recevez une notification si un produit est restauré à partir de la suppression. | |
product.merge |
Recevez une notification si un produit est fusionné avec un autre. | |
product.propertyChange |
Recevez une notification si un produit spécifique est modifié pour un produit dans le compte d'un client. | |
line_item.creation |
Recevez une notification si une ligne de produit est créée dans le compte d'un client. | |
line_item.deletion |
Recevez une notification si une ligne de produit est supprimée dans le compte d'un client. |
|
line_item.associationChange |
Recevez une notification si une ligne de produit a une association ajoutée ou supprimée entre elle-même et un autre objet de webhook pris en charge (contact, entreprise, transaction, ticket, ligne ou produit ou produit). | |
line_item.restore |
Recevez une notification si une ligne de produit est restaurée à partir de la suppression. | |
line_item.merge |
Recevez une notification si une ligne de produit est fusionnée avec une autre. | |
line_item.propertyChange |
Recevez une notification si une propriété spécifique est modifiée pour une ligne de produit dans le compte d'un client. |
Les types d'abonnement aux conversations suivants sont disponibles si vous utilisez l'API de boîte de réception de conversations et de messages, qui est actuellement en version bêta :
| Type d'abonnement | Domaine | Description |
|---|---|---|
conversation.creation |
conversations.read |
Recevez une notification si un nouveau fil de discussion est créé dans un compte. |
conversation.deletion |
Recevez une notification si un fil de discussion est archivé ou supprimé de façon réversible d'un compte. | |
conversation.privacyDeletion |
Recevez une notification si un fil de discussion est définitivement supprimé dans un compte. | |
conversation.propertyChange |
Recevez une notification si la propriété d'un fil est modifiée. | |
conversation.newMessage |
Recevez une notification si un nouveau message sur un fil de discussion est reçu. |
Pour les abonnements de modification de propriétés, vous devez spécifier la propriété pour laquelle vous souhaitez recevoir des notifications. Vous pouvez spécifier plusieurs abonnements de modification de propriétés. Si le compte d'un client ne dispose pas de la propriété que vous spécifiez dans un abonnement, vous ne recevrez aucun webhook de la part ce client pour cette propriété.
Certaines propriétés ne sont pas disponibles dans le cadre des abonnements de modifications de propriétés CRM. Ces propriétés sont :
num_unique_conversion_eventshs_lastmodifieddate
Si vous utilisez l'API de boîte de réception de conversations et de messages, qui est actuellement en version bêta, les propriétés suivantes sont disponibles :
assignedTo: le fil de conversation a été réattribué ou désattribué. Si le fil de conversation a été réattribué,propertyValuesera un ID d'acteur dans la charge utile des webhooks. S'il est désattribué, cette valeur sera vide.status: le statut du fil de conversation a changé. Dans la charge utile des webhooks,propertyValueseraOPENouCLOSED.isArchived: le fil de conversation a été restauré.propertyValuedans la charge utile des webhooks sera toujoursFALSE.
Vous pouvez créer des abonnements de webhook dans votre compte de développeur HubSpot.
- Dans votre compte de développeur HubSpot, accédez au tableau bord Applications.
- Cliquez sur le nom d'une application.
- Dans le menu latéral de gauche, accédez à Webhooks.
- Cliquez sur Créer un abonnement.
- Dans le panneau de droite, cliquez sur le menu déroulant Quels types d'objets ? et sélectionnez les objets pour lesquels vous souhaitez créer un abonnement.
- Cliquez sur le menu déroulant Écouter quels événements ? et sélectionnez les types d'événements.
- Si vous créez un abonnement pour des événements de modification de propriété, cliquez sur le menu déroulant Quelles propriétés ? et sélectionnez les propriétés à écouter.
- Cliquez sur S'abonner.
L'abonnement apparaîtra dans les paramètres des webhooks. Les nouveaux abonnements sont créés avec un statut En pause. Vous devrez activer l'abonnement pour l'envoi de webhooks :
- Dans la section Abonnements aux événements, passez le curseur sur le type d'objet et cliquez sur Afficher les abonnements.
- Sélectionnez la case à cocher à côté de l'événement, puis dans l'en-tête du tableau, cliquez sur Activer.
Vous pouvez créer des abonnements de façon programmée en utilisant les points de terminaison suivants. Vous devrez utiliser votre clé d'API de développeur lors des demandes à ces points de terminaison.
Un abonnement peut inclure les champs suivants :
| Champ | Description |
|---|---|
id
| Un nombre représentant l'ID unique d'un abonnement. |
createdAt
| L'heure en millisecondes à laquelle cet abonnement a été créé. |
createdBy
| L'ID d'utilisateur associé à l'utilisateur qui a créé l'abonnement. |
active
| Ce champ indique si l'abonnement est activé ou non et déclenche activement des notifications. La valeur peut être |
eventType
| Le type d'abonnement. Le tableau au début de cette section comprend les types d'abonnement disponibles. |
propertyName
| Le nom de la propriété pour laquelle l'abonnement écoutera les modifications. Cette option n'est nécessaire que pour les types d'abonnement aux modifications de propriété. |
Pour récupérer la liste des abonnements, effectuez une demande GET à webhooks/v3/{appId}/subscriptions.
La réponse sera un ensemble d'objets représentant vos abonnements. Chaque objet inclura des informations sur l'abonnement comme l'ID, la date de création, le type et, le cas échéant, une indication si l'abonnement est actuellement actif. Voici un exemple de réponse :
Pour créer un nouvel abonnement, effectuez une demande POST à webhooks/v3/{appId}/subscriptions.
Dans le corps de la demande, vous pouvez inclure les champs suivants :
| Champ | Description |
|---|---|
eventType
| Le type d'abonnement. |
propertyName
| Le nom de la propriété pour laquelle l'abonnement écoutera les modifications. Cette option n'est nécessaire que pour les types d'abonnement aux modifications de propriété. |
active
| Ce champ indique si l'abonnement est activé ou non et déclenche activement des notifications. La valeur peut être |
Vous n'avez pas besoin d'inclure id, createdAt ou createdBy, car ces champs sont automatiquement définis.
Par exemple, votre corps de demande peut ressembler à ce qui suit :
eventType doit être un type d'abonnement valide tel que défini dans la section ci-dessus et propertyName doit être un nom de propriété valide. Si un client n'a aucune propriété définie correspondant à cette valeur, cet abonnement ne déclenchera aucune notification.
Pour activer ou mettre en pause un abonnement, effectuez une demande PUT à webhooks/v3/{appId}/subscriptions/{subscriptionId}.
Dans le corps de la demande, ajoutez les éléments suivants :
| Champ | Description |
|---|---|
active
| Ce champ indique si l'abonnement est activé ou non et déclenche activement des notifications. La valeur peut être |
Pour supprimer un abonnement, effectuez une demande DELETE à webhooks/v3/{appId}/subscriptions/{subscriptionId}.
Le point de terminaison pour l'URL cible que vous spécifiez dans les paramètres de webhook de votre application recevra des demandes POST contenant des données au format JSON de HubSpot.
Pour vérifier que les demandes que vous obtenez au point de terminaison de webhook proviennent bien de HubSpot, HubSpot renseigne un en-tête X-HubSpot-Signature avec une fonction de hachage SHA-256 composée du secret client de votre application et des détails de la demande. Découvrez-en davantage sur la validation des signatures des demandes.
Utilisez les tableaux ci-dessous pour afficher des détails sur les champs pouvant être contenus dans la charge utile.
| Champ | Description |
|---|---|
objectId
| L'ID de l'objet qui a été créé, modifié ou supprimé. Il s'agit de l'ID du contact pour les contacts, de l'ID de l'entreprise pour les entreprises, de l'ID de transaction pour les transactions et de l'ID de fil pour les conversations. |
propertyName
| Ce champ est uniquement envoyé pour les abonnements aux modifications de propriété. Il s'agit du nom de la propriété modifiée. |
propertyValue
| Ce champ est uniquement envoyé pour les abonnements aux modifications de propriété et représente la nouvelle valeur définie pour la propriété qui a déclenché la notification. |
changeSource
| La source de la modification. Cela peut être l'une des sources de modification qui apparaissent dans les historiques des propriétés de contact. |
eventId
| L'ID unique de l'événement qui a déclenché cette notification. Cette valeur n'est pas forcément unique. |
subscriptionId
| L'ID de l'abonnement qui a déclenché une notification sur l'événement. |
portalId
| L'ID de compte HubSpot du client où l'événement s'est produit. |
appId
| L'ID de votre application Ce champ est utilisé dans le cas où plusieurs applications pointent vers la même URL de webhook. |
occurredAt
| Lorsque cet événement s'est produit, un horodatage en millisecondes. |
eventType
| Le type d'événement concerné par cette notification. Consultez la liste des types d'abonnement pris en charge dans la section des abonnements aux webhooks. |
attemptNumber
| Numéro de la tentative de notification de votre service concernant cet événement (à partir de 0). Si votre service expire ou renvoie une erreur comme indiqué dans la section Nouvelles tentatives ci-dessous, HubSpot tentera à nouveau d'envoyer la notification. |
messageId
| Ce champ est uniquement envoyé lorsqu'un webhook est à l'écoute de nouveaux messages dans un fil. Il s'agit de l'ID du nouveau message. |
messageType
| Ce champ est uniquement envoyé lorsqu'un webhook est à l'écoute de nouveaux messages dans un fil. Il représente le type de message que vous envoyez. Cette valeur peut être |
| Champ | Description |
|---|---|
primaryObjectId
| L'ID du gagnant de la fusion, qui est la fiche d'informations qui reste après la fusion. Dans l'interface utilisateur de fusion HubSpot, il s'agit de la fiche d'informations sur la droite. |
mergedObjectIds
| Un tableau des ID qui représentent les fiches d'informations qui sont fusionnées dans le gagnant de la fusion. Dans l'interface utilisateur de fusion HubSpot, il s'agit de la fiche d'informations sur la gauche. |
newObjectId
| L'ID de la fiche d'informations qui est créée à la suite de la fusion. Celui-ci est distinct de |
numberOfPropertiesMoved
| Un entier représentant le nombre de propriétés transférées au cours de la fusion. |
| Champ | Description |
|---|---|
associationType
| Le type d'association, qui sera l'un des suivants :
|
fromObjectId
| L'ID de la fiche d'informations à partir de laquelle la modification d'association a été effectuée. |
toObjectId
| L'ID de la fiche d'informations secondaire dans l'événement d'association. |
associationRemoved
| Un booléen qui représente les éléments suivants :
|
isPrimaryAssociation
| Un booléen qui représente les éléments suivants :
Remarque : La création d'une instance d'association principale entre deux fiches d'informations d'objets entraînera également la création de l'association non principale correspondante. Cela peut entraîner deux messages de webhook. |
Comme indiqué ci-dessus, vous devez vous attendre à recevoir plusieurs objets dans une seule demande. La taille du lot peut varier, mais elle restera inférieure à 100 notifications. HubSpot enverra plusieurs notifications uniquement lorsqu'un grand nombre d'événements se produiront dans un délai court. Par exemple, si vous êtes abonné aux nouveaux contacts et qu'un client importe un grand nombre de contacts, HubSpot vous enverra les notifications pour ces contacts dans des lots et non une par demande.
HubSpot ne garantit pas que vous recevrez ces notifications dans l'ordre chronologique. Utilisez la propriété occuredAt pour chaque notification pour déterminer quand est survenu l'événement qui a déclenché la notification.
HubSpot ne garantit pas non plus que vous ne recevrez qu'une seule notification pour un événement. Bien que cela soit rare, il est possible que HubSpot vous envoie plusieurs fois la même notification.
Les utilisateurs HubSpot peuvent supprimer définitivement une fiche d'informations de contact pour répondre à la législation en matière de confidentialité. Découvrez-en davantage sur la suppression conformément au RGPD.
Vous pouvez vous abonner au type d'abonnement contact.privacyDeletion pour recevoir des notifications de webhook lorsqu'un utilisateur effectue une suppression de contact conformément à la confidentialité.
Les notifications de suppression conformément à la confidentialité ont un comportement spécial :
- Un événement de suppression conformément à la confidentialité déclenche également l'événement de suppression du contact. Vous recevrez donc deux notifications si vous êtes abonné aux deux événements.
- Ces notifications ne seront pas nécessairement envoyées dans le bon ordre ou dans le même lot de messages. Vous devrez utiliser l'ID d'objet pour faire correspondre les différents messages.
Pour vérifier que les demandes que vous obtenez au point de terminaison de webhook proviennent bien de HubSpot, HubSpot dispose d'un en-tête X-HubSpot-Signature avec une fonction de hachage SHA-256 de concaténation de l'app-secret pour votre application et le corps de demande envoyé.
Pour vérifier cette signature, concaténez le secret de votre application et le corps non analysé de la demande que vous traitez, et obtenez un hachage SHA-256 du résultat. Comparez le hachage résultant avec la valeur de X-HubSpot-Signature. Si ces valeurs sont identiques, cette demande provient de HubSpot ou la demande provenait d'une autre personne qui connait le secret de votre application (lequel doit rester secret).
Si ces valeurs sont différentes, cette demande peut avoir été modifiée en transit ou quelqu'un peut usurper les notifications de webhook à votre point de terminaison.
Découvrez-en davantage sur la validation des demandes de signature.
Si votre service rencontre des problèmes de traitement des notifications, HubSpot tentera d'envoyer à nouveau les notifications jusqu'à 10 fois.
HubSpot procèdera à de nouvelles tentatives dans les cas suivants :
- La connexion a échoué : HubSpot ne parvient pas à ouvrir une connexion HTTP de l'URL de webhook fournie.
- Expiration : votre service prend plus de cinq secondes pour renvoyer une réponse à un lot de notifications.
- Codes d'erreur : votre service répond avec un code de statut HTTP (4xx ou 5xx).
Les notifications seront renvoyées jusqu'à 10 fois. Ces tentatives seront réparties sur les 24 heures suivantes, avec des délais différents entre les demandes. Afin d'éviter la récupération au même moment d'un grand nombre d'échecs concomitants, les notifications individuelles feront l'objet d'une distribution au hasard.
Merci d'avoir partagé votre avis.