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.

 

Domaines

Pour utiliser les webhooks, votre application devra être configurée pour exiger le domaine contacts. Ce domaine doit être configuré avant que vous puissiez créer des abonnements de webhook, soit depuis votre compte de développeur dans les paramètres de l'application, soit via l'API Webhooks pour configurer les abonnements. 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 contacts tant que vous ne supprimerez pas tous les abonnements de webhook de votre application.

 

Configuration de webhooks

Remarque : Les paramètres de webhook peuvent être mis en cache jusqu'à cinq minutes. L'application des modifications de l'URL du webhook, des limites de taux ou des paramètres d'abonnement peut prendre jusqu'à cinq minutes.

 

URL du webhook et limites de taux

Avant de configurer des abonnements de webhook, vous devez spécifier une URL à laquelle envoyer ces notifications. Vous pouvez également choisir le taux auquel votre point de terminaison peut gérer les requêtes.

La définition de ce taux permet d'envoyer des notifications aussi vite que possible, sans avoir trop de chargement sur 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 un retard des notifications.
  • 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.

 

Gestion via l'interface utilisateur

Vous pouvez gérer les paramètres de votre URL et vos taux via la page de configuration de votre application dans votre compte de développeur :

1. Dans le tableau de bord Applications, sélectionnez l'application pour laquelle vous souhaitez configurer des webhooks.
app_id_list

2. Sélectionnez l'élément Webhooks à gauche. Cet écran propose une interface que vous pouvez utiliser pour définir l'URL cible et la limite de ralentissement d'événement.

webhook_settings

Gestion via l'API

Ces points de terminaison vous permettent de définir par programme des paramètres de webhook pour une application. Il est recommandé d'utiliser l'interface utilisateur pour configurer vos applications. Vous devrez utiliser votre clé d'API de développeur lors des demandes à ces points de terminaison.

Champs de paramètres

Les paramètres présentent les champs suivants :

  • webhookUrl - L'URL vers laquelle seront envoyées les notifications de webhook. Elle doit être sur un serveur HTTPS.
  • maxConcurrentRequests - Limite de concomitance pour cette URL, telle que mentionnée dans URL du webhook et limite de concomitance.
Affichage des paramètres

Le point de terminaison suivant accède aux paramètres de webhook actuellement configurés pour votre application, le cas échéant :

GET https://api.hubapi.com/webhooks/v3/{appId}/settings

Le résultat ressemblera à ceci :

{
  « webhookUrl »: « https://testing.com/webhook »,
  « maxConcurrentRequests »: 20
}

Mise à jour des paramètres

Pour modifier ces paramètres, vous pouvez utiliser le point de terminaison suivant :

PUT https://api.hubapi.com/webhooks/v3/{appId}/settings

Avec un corps de requête comme ceci :

{
  « webhookUrl »: « https://testing.com/webhook-modified »,
  « maxConcurrentRequests »: 25
}
 

Validation :

  • webhookUrl doit être une URL HTTPS valide.
  • maxConcurrentRequests doit être un nombre supérieur à 5.

 

Abonnements de webhook

Une fois que vous avez configuré l'URL de votre webhook et les paramètres de limite de taux, 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 types d'abonnement suivants sont actuellement pris en charge :

  • Création de contacts
  • Suppression de contacts
  • Suppression de contacts conformément à la confidentialité (voir ci-dessous pour plus de détails)
  • Modification des propriétés de contact
  • Création d'entreprises
  • Suppression d'entreprises
  • Modifications des propriétés d'entreprise
  • Création de transactions
  • Suppression de transactions
  • Modifications des propriétés de transaction

 

Veuillez tenir compte de certains aspects concernant les abonnements :

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. Ces propriétés sont :


Propriétés de contact :

  • days_to_close
  • recent_conversion_event_name
  • recent_conversion_date
  • first_conversion_event_name
  • first_conversion_date
  • num_unique_conversion_events
  • num_conversion_events
  • hs_additional_emails

Propriétés de transaction :

  • num_associated_contacts

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. Lorsque vous avez activé un abonnement pour une application, il commencera automatiquement à obtenir les webhooks pour tous les clients qui ont installé votre application et vous commencerez alors à obtenir automatiquement les webhooks de tous les nouveaux clients qui installent votre intégration.

La création ou la modification de vos abonnements peuvent prendre jusqu'à cinq minutes.

 

Gestion des abonnements via l'interface utilisateur

Vous pouvez créer des abonnements de webhook via votre compte de développeur :

  1. Dans le tableau de bord de développeur Applications, sélectionnez l'application pour laquelle vous souhaitez envoyer des webhooks.
  2. Sélectionnez Abonnements de webhook.
  3. Cliquez sur Créer un abonnement.
    webhook_settings
  4. Sélectionnez le type d'objet (c.-à-d. un contact, une entreprise ou une transaction) et le type d'événement (c.-à-d. une création, une modification ou une suppression). Remarque : La suppression conformément à la confidentialité peut être sélectionnée uniquement lorsque « contacts » est le seul type d'objet sélectionné.
    create_webhook_subscription
  5. Pour les événements de modification de propriétés, sélectionnez la propriété en question (facultatif). Remarque : Vous pouvez également saisir manuellement des noms de propriétés, afin d'utiliser des propriétés personnalisées.

REMARQUE : Les nouveaux abonnements sont créés avec le statut Interrompu. Vous devrez activer l'abonnement pour l'envoi de webhooks.

activate_subscription

Gestion des abonnements via l'API

Ces points de terminaison permettent de créer des abonnements par programme. Il n'y a rien dans ces points de terminaison que vous ne puissiez pas effectuer via l'interface utilisateur, qui constitue le meilleur moyen pour configurer votre application. Vous devrez utiliser votre clé d'API de développeur lors des demandes à ces points de terminaison.

Champs d'abonnement

Un abonnement contient les champs suivants :

  • id - Nombre représentant l'ID unique d'un abonnement.
  • createdAt - Date de création de cet abonnement, il s'agit d'un horodatage en millisecondes.
  • createdBy - L'ID de l'utilisateur qui a créé cet abonnement.
  • enabled - Indique si cet abonnement est actuellement actif et déclencheur de notifications.
  • subscriptionDetails - Décrit les types d'événement couverts par cet abonnement.
  • subscriptionType - Chaîne représentant le type d'abonnement, tel que défini dans Types d'abonnement ci-dessous.
  • propertyName - Uniquement nécessaire pour les modifications de propriétés. Le nom de la propriété pour laquelle surveiller les modifications. Il ne peut s'agir que d'un seul nom de propriété.

 

Types d'abonnement

La propriété subscriptionType peut être l'une des valeurs suivantes :

  • contact.creation - Pour recevoir une notification si un contact est créé dans le compte d'un client.
  • contact.deletion - Pour recevoir une notification si un contact est supprimé dans le compte d'un client.
  • contact.privacyDeletion - Pour recevoir une notification si un contact est supprimé pour des raisons de confidentialité. Voir ci-dessous pour plus de détails.
  • contact.propertyChange - Pour recevoir une notification si une propriété spécifique est modifiée pour un contact dans le compte d'un client.
  • company.creation - Pour recevoir une notification si une entreprise est créée dans le compte d'un client.
  • company.deletion - Pour recevoir une notification si une entreprise est supprimée dans le compte d'un client.
  • company.propertyChange - Pour recevoir une notification si une propriété spécifique est modifiée pour une entreprise dans le compte d'un client.
  • deal.creation - Pour recevoir une notification si une transaction est créée dans le compte d'un client.
  • deal.deletion - Pour recevoir une notification si une transaction est supprimée dans le compte d'un client.
  • deal.propertyChange - Pour recevoir une notification si une propriété spécifique est modifiée pour une transaction dans le compte d'un client.

 

Obtention d'abonnements

Pour récupérer la liste des abonnements :

GET https://api.hubapi.com/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 activé. Voici un exemple de réponse :

// [ { "id": 25, "createdAt": 1461704185000, "createdBy": 529872, "subscriptionDetails": { "subscriptionType": "contact.propertyChange", "propertyName": "lifecyclestage" }, "enabled": true }, { "id": 59, "createdAt": 1462388498000, "createdBy": 529872, "subscriptionDetails": { "subscriptionType": "company.creation" }, "enabled": false }, { "id": 108, "createdAt": 1463423132000, "createdBy": 529872, "subscriptionDetails": { "subscriptionType": "deal.creation" }, "enabled": true } ]
Créer un nouvel abonnement

Pour créer de nouveaux abonnements :

POST https://api.hubapi.com/webhooks/v1/{appId}/subscriptions

Avec un corps de requête comme ceci :

// { "subscriptionDetails": { "subscriptionType":"company.propertyChange", "propertyName": "companyname" }, "enabled": false }
Les champs du corps de cette demande correspondent à ceux définis dans Champs d'abonnement. Toutefois, avec ce point de terminaison, vous ne pouvez pas spécifier idcreatedAt ou createdBy, car ces champs sont automatiquement définis.

Validation :

subscriptionType doit être un type d'abonnement valide tel que défini dans la section Types d'abonnement.

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.

enabled doit être true ou false.

 
Mettre à jour un abonnement

Vous ne pouvez mettre à jour que l'indicateur d'activation d'un abonnement. Pour ce faire, utilisez le point de terminaison suivant :

PUT https://api.hubapi.com/webhooks/v1/{appId}/subscriptions/{subscriptionId}

Corps de la demande :

{ "enabled" : false }

Supprimer un abonnement

Pour supprimer un abonnement, vous pouvez appeler le point de terminaison suivant :

DELETE https://api.hubapi.com/webhooks/v1/{appId}/subscriptions/{subscriptionId}

 

Charges utiles des webhooks

Le point de terminaison pour l'URL que vous spécifiez dans les paramètres de webhook recevra des demandes telles que :

Type de méthode : POST

Headers:

Content-Type: Application/Json
X-HubSpot-Signature : Hachage du secret d'application et du corps de demande (voir ci-dessous pour plus de détails).


Exemple de corps de demande :

// [ { "objectId": 1246965, "propertyName": "lifecyclestage", "propertyValue": "subscriber", "changeSource": "ACADEMY", "eventId": 3816279340, "subscriptionId": 25, "portalId": 33, "appId": 1160452, "occurredAt": 1462216307945, "subscriptionType":"contact.propertyChange", "attemptNumber": 0 }, { "objectId": 1246978, "changeSource": "IMPORT", "eventId": 3816279480, "subscriptionId": 22, "portalId": 33, "appId": 1160452, "occurredAt": 1462216307945, "subscriptionType": "contact.creation", "attemptNumber": 0 } ]

Champs de demande :

  • objectId : L'ID de l'objet qui a été créé/modifié/supprimé. Il s'agit de vid pour les contacts, companyId pour les entreprises et dealId pour les transactions.
    propertyName : Ce champ est uniquement envoyé lorsque la notification concerne une modification de propriété. Il s'agit du nom de la propriété modifiée.
  • propertyValue : Ce champ est uniquement envoyé lorsque la notification concerne une modification de propriété. Il s'agit de la nouvelle valeur définie pour cette propriété qui a déclenché cette notification.
  • changeSource : La source de cette modification. Cela peut être l'une des sources de modification que vous trouvez dans les historiques des propriétés de contact.
  • eventId : L'ID unique de l'événement qui a déclenché cette notification.
  • subscriptionId : L'ID de l'abonnement qui a déclenché l'envoi d'une notification de cet événement.
  • portalId : L'ID du portail du client d'où provient cet événement.
  • appId : L'ID de votre application (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.
  • subscriptionType : Le type d'événement concerné par cette notification. Consultez la liste des types d'abonnement dans la section Types d'abonnement.
  • 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 Nouvelles tentatives ci-dessous, HubSpot tentera à nouveau d'envoyer la notification à votre service.

 

REMARQUE SUR LES LOTS : Comme indiqué ci-dessus, vous recevrez plusieurs notifications dans une seule demande. La taille du lot peut varier, mais elle restera inférieure à 100 notifications. Vous recevrez plusieurs notifications uniquement lorsqu'un grand nombre d'événements se produisent 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.

REMARQUE SUR L'ORDRE : Il est possible que vous ne receviez pas ces notifications dans l'ordre chronologique. Utilisez la propriété occuredAt pour chaque notification pour déterminer quand la notification est survenue.

REMARQUE SUR LA SPÉCIFICITÉ : Il est possible que vous receviez plusieurs notifications pour un même événement. Bien que cela soit rare, il est possible que HubSpot vous envoie plusieurs fois la même notification.

 

Gestion des suppressions de contacts conformément à la confidentialité

Les utilisateurs HubSpot peuvent supprimer définitivement une fiche d'informations de contact pour répondre à la législation en matière de confidentialité. Consultez l'article d'aide suivant pour en savoir plus sur cette fonctionnalité : https://knowledge.hubspot.com/fr/articles/kcs_article/contacts/how-do-i-perform-a-gdpr-compliant-delete-in-hubspot.

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

Remarque : 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 normal contact.delete. Vous recevrez donc deux notifications si vous êtes abonné aux deux événements.
  • Il n'est pas garanti que ces notifications soient envoyées dans le bon ordre ou dans le même lot de messages. Vous devrez utiliser objectId pour faire correspondre les différents messages.

 

Sécurité

Remarque : Les webhooks utilisent la première version de X-HubSpot-Signature. Veuillez consulter cette page pour plus de détails sur la validation de cette version de signature et cette page pour plus de détails sur la validation des demandes en général.

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 d'une autre personne qui connait le secret de votre application, lequel doit rester secret). Si ces valeurs ne correspondent pas, cette demande peut avoir été modifiée en transit ou quelqu'un peut usurper les notifications de webhook à votre point de terminaison.

Nouvelles tentatives

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é - Si HubSpot ne parvient pas à ouvrir une connexion HTTP de l'URL de webhook fournie.
Expiration - Si votre service prend plus de 5 secondes pour renvoyer une réponse à un lot de notifications.
Codes d'erreur - Si 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.

Limites

Vous pouvez créer un maximum de 1 000 abonnements par application. Si vous tentez d'en créer plus, vous recevrez une mauvaise requête 400 avec le corps suivant :

// { "status": "error", "message": "Couldn't create another subscription. You've reached the maximum number allowed per application (1000).", "correlationId": "2c9beb86-387b-4ff6-96f7-dbb486c00a95", "requestId": "919c4c84f66769e53b2c5713d192fca7" }

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.