Configurer les Webhooks de l'entreprise

Objectif

Configurer la fonction Webhooks pour recevoir des notifications en cas de modification d'une ou plusieurs ressources API Procore au niveau entreprise.

Contexte

La fonctionnalité Webhooks permet aux développeurs et intégrateurs tiers de préciser une ou plusieurs ressources API Procore pour lesquelles ils souhaitent être avertis lorsque des activités de création, de mise à jour ou de suppression se produisent. L'interface utilisateur permettant de configurer la fonctionnalité Webhooks est disponible via l'outil Admin de l'entreprise dans Procore.

Les avantages de la fonctionnalité Webhooks sont notamment les suivants :

Suppression du besoin de logique/code de sondage dans les intégrations tierces afin de déterminer les modifications de ressources
Amélioration des performances en remplaçant les sondages par des mises à jour asynchrones
Efficacité accrue car le code ne doit être exécuté que lorsqu'une ressource change
Réduction du risque de dépassement des plafonds de taux API de Procore

Éléments à prendre en compte

Autorisations utilisateur requises :
- Autorisations de niveau « Admin » dans l'outil Admin au niveau entreprise.
Informations pour les développeurs :
- Consultez les guides Introduction à Webhooks et Utilisation des API Webhooks sur le portail des développeurs pour obtenir des informations sur le développement de votre application ou de votre intégration afin de prendre correctement en charge les Webhooks.

Procédure

Accédez à l'outil Admin au niveau entreprise.
Sous « Paramètres de l'entreprise », cliquez sur Webhooks.
Ceci ouvre la page de configuration « Webhooks » qui comprend un champ Terminal de notification pour entrer l'URL de votre serveur Web et une grille de ressources pour sélectionner les ressources et les actions de modification correspondantes pour lesquelles vous souhaitez recevoir une notification.

Procédez comme suit :
1. Terminal de notification. Entrez l'URL du terminal sur votre serveur Web qui gérera les demandes POST provenant de Procore.
2. En-tête d'autorisation. (Facultatif) Saisissez le jeton d'autorisation que vous souhaitez voir placé dans l'en-tête d'une requête POST provenant de Procore. Bien que ce champ puisse être utilisé pour définir toutes les informations d'en-tête d'autorisation que vous souhaitez, il est le plus souvent utilisé pour spécifier les informations d'autorisation en utilisant la syntaxe : , où est le type d'autorisation (« Basic », « Token », « Bearer », etc.) et est la valeur du jeton. Par exemple, une entrée valide pour ce champ serait Basic c3a24b8208ac5199d083d54a1234e94b8864.
3. Enregistrer le point de terminaison. Cliquez sur ce bouton pour enregistrer le point de terminaison. Si vous avez entré une adresse valide et bien formée dans le champ Notification de point de terminaison, une bannière VERTE apparaît en haut de la page indiquant que le point a été enregistré avec succès. S'il y a des problèmes avec l'URL que vous avez saisie, une bannière d'avertissement s'affichera décrivant le problème probable.
Dans la grille de ressources, cochez les cases « Créer », « Mettre à jour » et « Supprimer » pour toute ressource pour laquelle vous souhaitez recevoir les notifications correspondantes. Notez que vos sélections d'actions prennent effet immédiatement dès que vous les faites, il n'est pas nécessaire de« soumettre »vos modifications.
Remarque : gardez à l'esprit que, lorsque vous configurez des Webhooks, vous ne faites qu'identifier les ressources/actions pour lesquelles vous souhaitez recevoir des notifications. Vous ne recevrez une notification que lorsqu'une modification réelle sera apportée à une ressource.

Livraisons Webhooks

Un registre de Livraisons Webhooks à votre terminal de notification est disponible au bas de la page Webhooks de l'entreprise. La section Livraisons permet de voir rapidement le statut des événements que Procore a envoyés (ou tenté d'envoyer) à votre serveur de notification. Les livraisons réussies et échouées sont incluses par défaut dans la vue. Vous pouvez utiliser la case à cocher Afficher uniquement les échecs pour filtrer la vue afin d'afficher uniquement les livraisons qui ont échoué.

Les livraisons les plus récentes apparaissent en haut de la section Livraisons. En cliquant sur une entrée de livraison, vous obtenez des détails sur la charge utile de la demande, les en-têtes de réponse et le corps de la réponse.

L'affichage du registre des livraisons est paginé avec un maximum de 25 livraisons affichées à la fois. Cliquez sur « Plus de livraisons » pour afficher la prochaine série de 25 livraisons.

Surveillance et alarmes

Nous vous recommandons vivement de mettre en place une surveillance adéquate de vos serveurs de terminaux de notification afin de garantir que toute interruption ou tout autre problème lié aux performances soit identifié et que vous soyez averti en temps utile par un système d'alarme fiable. Il existe de nombreux systèmes de surveillance commerciaux qui peuvent servir à cette fin, notamment Datadog, New Relic et bien d'autres. Ces services offrent des fonctions de surveillance robustes qui vous permettent de visualiser facilement l'intégrité de votre système grâce à des tableaux et des graphiques configurables et à des analyses en temps réel. Ces services fournissent également des alertes intégrées, afin que vous soyez rapidement averti en cas de problème.

Voir aussi

Pour des informations sur la configuration des Webhooks au niveau du projet, voir Configurer les Webhooks du projet.