Webhooks : envoyer les alertes CostGuard à vos outils
Comment enregistrer une destination, conserver son secret de signature, vérifier chaque livraison et désactiver une destination, et quels événements CostGuard envoie.
À quoi sert cette page
Webhooks envoie les alertes de l'espace de travail à des systèmes que vous exploitez, comme un bot de discussion, un outil d'incidents ou votre propre service. La page dit quelles destinations reçoivent quels événements, et si les livraisons récentes sont arrivées.
CostGuard signe chaque envoi et réessaie un envoi échoué selon un calendrier fixe, jusqu'à cinq tentatives. Seuls les évènements listés ci-dessous sont envoyés ; rien d'autre ne sort.
Avant de commencer
Il vous faut :
- L'offre Pro ou Enterprise ; les autres offres voient un exemple identifié.
- Une adresse HTTPS sur un hôte public qui accepte une requête POST et vérifie la signature avant de faire confiance à la requête.
Enregistrer une destination
Dans « Enregistrer une destination », renseignez :
- « Nom » : un nom court et simple que vous reconnaîtrez dans les listes.
- « URL de destination » : Doit être une adresse HTTPS sur un hôte public. CostGuard ne vérifie pas que l'adresse est joignable ni qu'elle vous appartient.
- « Évènements à envoyer » : Risque budgétaire détecté, Risque de prévision détecté et Échec de la synchronisation des coûts, les trois événements que CostGuard produit aujourd'hui.
Sous « Non produits actuellement », la page nomme les autres catégories d'événements, qui ne peuvent pas être choisies : CostGuard nomme ces catégories d'évènements mais n'en déclenche actuellement aucune ; elles ne peuvent donc pas être sélectionnées. Rien ne serait jamais envoyé pour elles.
« Enregistrer la destination » active la destination immédiatement. Un espace de travail peut enregistrer jusqu'à dix destinations ; le panneau compte combien sont utilisées.
Le secret de signature
Quand une destination est enregistrée, la page affiche une seule fois son « Clé de signature ». Copiez-la maintenant. Elle n'est affichée qu'une fois et ne pourra pas l'être à nouveau ; si vous la perdez, générez-en une nouvelle, ce qui invalide l'ancienne.
Chaque envoi porte un en-tête X-CostGuard-Signature, une signature HMAC-SHA256 calculée avec la clé de signature de la destination, et un en-tête X-CostGuard-Timestamp. Votre récepteur vérifie la signature avant de faire confiance à la requête.
« Générer une nouvelle clé » demande d'abord confirmation : le secret actuel cesse aussitôt de fonctionner, et votre récepteur refuse les livraisons tant qu'il n'a pas le nouveau.
Destinations enregistrées
« Destinations enregistrées » liste chaque destination avec les événements qu'elle reçoit, « État », « Dernier envoi » et « Enregistrée (UTC) ». Ses actions :
- « Désactiver » et « Activer » : Tant qu'une destination est désactivée, aucun nouvel envoi n'est créé pour elle ; un envoi qui attendait déjà part dès qu'elle est réactivée.
- « Générer une nouvelle clé » : voyez le secret de signature ci-dessus.
- « Supprimer » : Elle est supprimée avec sa clé de signature, et plus rien ne lui est envoyé.
La désactivation, l'émission d'un nouveau secret et la suppression demandent chacune une confirmation ; l'activation se fait immédiatement.
Livraisons récentes
Les envois les plus récents de cet espace de travail, jusqu'à cent, du plus récent au plus ancien. Les heures sont en UTC. Chaque livraison a un statut :
- « Livré » : votre point de terminaison l'a acceptée.
- « En attente » : elle va être tentée, ou retentée selon le calendrier fixe.
- « Refusé » : votre point de terminaison l'a refusée, ou l'adresse ne peut pas être appelée ; elle n'est pas retentée.
- « Abandonné » : cinq tentatives ont été faites sans que votre point de terminaison l'accepte à temps.
« Tentatives » compte les tentatives, et « Détail » dit simplement ce qui s'est passé, par exemple « Votre point de terminaison n'a pas répondu à temps » ou « Votre point de terminaison a refusé la requête ». Une livraison vers une destination supprimée depuis affiche « Une destination supprimée ».
Comment fonctionnent les webhooks
Un envoi que votre point de terminaison n'a pas accepté à temps est retenté après une, cinq, quinze et soixante minutes, soit cinq tentatives en tout ; après la cinquième, il apparaît comme « Abandonné ». Un envoi refusé par votre point de terminaison, ou une adresse que CostGuard ne peut pas appeler, n'est pas retenté.
Les événements portent les mêmes alertes que l'espace de travail déclenche dans « Règles d'alerte » ; un événement n'est envoyé que lorsqu'une telle alerte est déclenchée.
Les webhooks sont distincts des alertes par e-mail et dans l'application : « Paramètres de notification » les règle, et « Historique d'envoi des alertes » les liste.
Ce que vous pouvez voir à la place des chiffres
Pendant la lecture, des barres grises occupent la place des panneaux. Ensuite, la page peut afficher l'un de ces états à la place :
- « Impossible de lire les destinations enregistrées » : Cela ne signifie pas que l'espace de travail n'en a aucune. Réessayez.
- Cet espace de travail n'a enregistré aucune destination.
- « Impossible de lire les envois récents » : Cela ne signifie pas que rien n'a été envoyé. Rechargez la page pour réessayer.
- CostGuard n’a pas pu confirmer si cette modification a été enregistrée. La liste ci-dessous montre l’état actuel de l’espace de travail.
Quand votre offre n'inclut pas les webhooks
En Free, Starter et Growth, la page affiche un exemple fixe sous l'étiquette « Données d'exemple », avec la phrase « Votre offre actuelle n'inclut pas cette fonctionnalité. Les chiffres affichés ici sont un exemple, pas vos données. »
L'exemple montre des destinations et des livraisons inventées, sans bouton, sans secret et sans aucune de vos adresses.
« Comparer les offres » ouvre la page des tarifs dans un nouvel onglet. CostGuard décide sur le serveur de ce que votre offre inclut ; l'exemple n'est que la façon dont la page l'affiche.
Ce que comprend chaque offre
Le tableau indique la première offre qui comprend chaque partie de la page. Toutes les offres supérieures la comprennent aussi.
| Fonctionnalité | Free | Starter | Growth | Pro | Enterprise |
|---|---|---|---|---|---|
| Un exemple de la page, signalé comme tel | Inclus | Inclus | Inclus | Inclus | Inclus |
| L'enregistrement de destinations et l'envoi d'événements | Non inclus | Non inclus | Non inclus | Inclus | Inclus |
Pro et Enterprise comprennent les webhooks ; Free, Starter et Growth affichent l'exemple identifié. L'offre est vérifiée sur le serveur, et la page n'affiche jamais de prix.
Résolution des problèmes
Mon récepteur rejette la signature
Le récepteur détient un secret ancien ou mal saisi. Émettez un nouveau secret, enregistrez-le aussitôt dans votre récepteur, et vérifiez que la signature est calculée sur la requête telle qu'elle a été reçue.
Les livraisons affichent « Abandonné »
Votre point de terminaison n'a accepté à temps aucune des cinq tentatives : il était injoignable, trop lent ou a renvoyé une erreur. Corrigez-le ; les nouveaux événements sont livrés dès qu'il répond.
La page refuse mon adresse
CostGuard n'a pas pu utiliser cette adresse. Elle doit être en HTTPS, sur un hôte public et sur un port standard. Une adresse contenant un nom d'utilisateur ou un mot de passe est également refusée.
Je ne peux pas enregistrer une autre destination
L'espace de travail a enregistré dix destinations, le maximum autorisé. Supprimez d'abord une destination que vous n'utilisez plus.