Webhooks

Un abonnement webhook fait envoyer par Kyvernon une requête HTTP à un destinataire pour chaque événement correspondant. Le corps est un document CloudEvents 1.0 en JSON, signé avec un secret partagé. Les alarmes peuvent envoyer leurs changements d'état aux abonnements qui portent une étiquette, et le résumé quotidien de consommation est livré de la même façon. Gérer les webhooks demande Kyvernon.Webhook.Manage.

Le destinataire doit être joignable depuis le contrôleur. Les adresses privées, de bouclage et de lien local sont refusées sauf si un administrateur les autorise ; consultez Cibles restreintes. Choisissez un secret d'au moins 16 caractères : Kyvernon l'utilise pour signer chaque livraison, et le destinataire l'utilise pour les vérifier.

Dans la console

1. Ouvrez la page d'accueil (Accueil) et sélectionnez Webhooks sous Raccourcis.

:::screen webhooks

Le tableau montre chaque abonnement avec son Adresse, son État, les Événements qu'il reçoit, ses Libellés et les compteurs Livrés, Échoués et Lettres mortes.

2. Sélectionnez Nouveau webhook. Saisissez le Nom et l'Adresse du destinataire. Une adresse https est recommandée.
3. Saisissez le Secret partagé, ou sélectionnez Générer pour en créer un. Il compte au moins 16 caractères et n'est plus affiché ensuite, donc conservez-le là où le destinataire peut le lire.
4. Sous Types d’événements, listez les types d'événements à envoyer, séparés par des virgules. Vide, le champ envoie tous les événements. Sous Libellés, indiquez les étiquettes de l'abonnement, pour qu'une alarme puisse le choisir ; consultez les alarmes.
5. Réglez les Tentatives par événement, de 1 à 20 (5 par défaut). Après la dernière tentative, l'événement devient une lettre morte. Renseignez le Locataire uniquement pour une intégration en libre-service : l'abonnement ne reçoit alors que les événements de ce locataire ; consultez l'intégration au portail.

:::screen webhook-create

6. Sélectionnez Créer le webhook.
7. Dans la ligne du nouvel abonnement, sélectionnez Envoyer un test. Un événement de test part vers le destinataire, et un message indique s'il a répondu avec un statut de la plage 2xx.
8. Sélectionnez Journal d’envoi pour lire le journal des livraisons : les totaux depuis la création de l'abonnement, les lettres mortes avec leurs tentatives et leur dernière erreur, et les tests envoyés depuis cette page. Envoyer un test figure aussi dans la boîte de dialogue.

:::screen webhook-log

Modifier modifie un abonnement ; laissez le secret vide pour conserver celui qui est stocké, et utilisez Le webhook est activé pour suspendre les livraisons. Supprimer le supprime, et ses lettres mortes sont perdues ; les alarmes qui envoient vers ses étiquettes ne l'atteignent plus.

Résultat

L'abonnement figure dans la liste, le test affiche Livré, et le destinataire reçoit désormais chaque événement correspondant.

Automatisation

Avec la CLI

Le secret vient de la variable d'environnement KYVERNON_WEBHOOK_SECRET ou de --secret :

export KYVERNON_WEBHOOK_SECRET="<secret of at least 16 characters>"
kyvernon webhooks create ops-receiver --url https://hooks.example.com/kyvernon \
  --event VmPoweredOffEvent --event HostDisconnectedEvent --label ops-pager --max-attempts 5
kyvernon webhooks test <id>
kyvernon webhooks update <id> --body-file webhook.json
kyvernon webhooks dead-letters <id>
kyvernon webhooks deliveries <id>

--event et --label peuvent être répétés. webhooks deliveries <id> affiche les 50 dernières livraisons d'un abonnement. webhooks list affiche les compteurs de chaque abonnement, et webhooks delete <id> en supprime un. Pour vérifier une livraison dans un shell, calculez la signature sur l'horodatage, un point et le corps :

printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$KYVERNON_WEBHOOK_SECRET"

Avec l'API

POST /v1/webhooks crée un abonnement avec name, url, secret, eventTypes, labels, maxAttempts et tenant. GET /v1/webhooks les liste, PUT /v1/webhooks/{id} en modifie un, POST /v1/webhooks/{id}/test envoie un test, GET /v1/webhooks/{id}/dead-letters lit les lettres mortes et DELETE /v1/webhooks/{id} en supprime un. Le service gRPC WebhookService offre les mêmes opérations.

GET /v1/webhooks/{id}/deliveries exige Kyvernon.Webhook.Manage. Il renvoie les 50 dernières livraisons de l'abonnement, la plus récente d'abord. Elles sont conservées dans le store répliqué avec l'abonnement. Les livraisons de test sont aussi journalisées. Chaque livraison a ces champs :

Contenu d'une livraison

Chaque livraison est un POST avec le type de contenu application/cloudevents+json et ces en-têtes :

Le type CloudEvents est kyvernon.event.<event type>, par exemple kyvernon.event.VmPoweredOffEvent, et data contient l'événement tel que l'API le montre. Le résumé quotidien de consommation a le type kyvernon.usage.daily_summary ; abonnez-vous avec le type d'événement UsageDailySummary.

Vérifiez une livraison avant de lui faire confiance. Calculez le HMAC sur l'horodatage, un point et le corps brut, comparez-le à l'en-tête en temps constant, et rejetez un horodatage trop ancien. Une livraison répétée porte le même identifiant d'événement, donc un destinataire peut ignorer les doublons.

Nouvelles tentatives et lettres mortes

Une livraison réussit quand le destinataire répond avec un statut de la plage 2xx en moins de 10 secondes. Sinon, Kyvernon réessaie avec un délai qui part d'une seconde et double jusqu'à 60 secondes, jusqu'à ce que le nombre de tentatives soit atteint. Kyvernon ne suit aucune redirection. Après la dernière tentative, l'événement est placé dans les lettres mortes de l'abonnement, avec le nombre de tentatives et la dernière erreur, dans une liste bornée. Réparez le destinataire, envoyez un test pour vérifier qu'il est joignable, et utilisez les identifiants d'événement pour retrouver les événements dans la liste des événements.

Cibles restreintes

Kyvernon refuse une cible qui est une adresse de bouclage, privée, de lien local, partagée (NAT de niveau opérateur), de multidiffusion ou une autre adresse à usage spécial, afin qu'un abonnement ne puisse pas atteindre des services internes. La vérification s'exécute à la création de l'abonnement et de nouveau à chaque livraison, sur les adresses auxquelles le nom d'hôte correspond. Le refus est error.webhook.target_restricted. Quand le destinataire se trouve volontairement dans votre propre réseau, un administrateur liste ce réseau, par exemple 198.51.100.0/24, comme réseau autorisé dans la section [webhooks] de la configuration du contrôleur et redémarre le contrôleur. La référence de configuration donne la clé.

Voir aussi

• Les événements listent les types d'événements.
• Les alarmes livrent les changements d'état par étiquette.
• La consommation décrit le résumé quotidien.