Webhooks

Een webhookabonnement zorgt ervoor dat Kyvernon voor elke overeenkomende gebeurtenis een HTTP-verzoek naar een ontvanger stuurt. De body is een CloudEvents 1.0-document in JSON, ondertekend met een gedeeld geheim. Alarmen kunnen hun statuswijzigingen sturen naar de abonnementen die een label dragen, en de dagelijkse verbruikssamenvatting wordt op dezelfde manier afgeleverd. Het beheren van webhooks vraagt Kyvernon.Webhook.Manage.

De ontvanger moet bereikbaar zijn vanaf de controller. Privé-, loopback- en link-local-adressen worden geweigerd tenzij een beheerder ze toestaat; zie Beperkte doelen. Kies een geheim van minstens 16 tekens: Kyvernon gebruikt het om elke levering te ondertekenen, en de ontvanger gebruikt het om ze te verifiëren.

In de console

1. Open de startpagina (Start) en selecteer Webhooks onder Snelkoppelingen.

   (Groter weergeven)

   Grotere weergave sluiten

   De tabel toont elk abonnement met zijn Adres, Status, de Gebeurtenissen die het ontvangt, zijn Labels en de tellers Geleverd, Mislukt en Dead letters.

2. Selecteer Nieuwe webhook. Voer de Naam en de Adres van de ontvanger in. Een https-adres wordt aanbevolen.
3. Voer het Gedeeld geheim in, of selecteer Genereren om er een te maken. Het heeft minstens 16 tekens en wordt niet opnieuw getoond, dus bewaar het waar de ontvanger het kan lezen.
4. Geef onder Gebeurtenistypen de te sturen gebeurtenistypen op, gescheiden door komma's. Leeg stuurt elke gebeurtenis. Geef onder Labels de labels van het abonnement op, zodat een alarm het kan kiezen; zie Alarmen.

5. Stel de Pogingen per gebeurtenis in, van 1 tot 20 (5 is de standaardwaarde). Na de laatste poging wordt de gebeurtenis een dead letter. Vul Tenant alleen in voor een self-serviceintegratie: het abonnement ontvangt dan alleen de gebeurtenissen van die tenant; zie Portalintegratie.

   (Groter weergeven)

   Grotere weergave sluiten
6. Selecteer Webhook maken.
7. Selecteer in de rij van het nieuwe abonnement Test versturen. Er gaat een testgebeurtenis naar de ontvanger, en een bericht meldt of die heeft geantwoord met een status in het 2xx-bereik.

8. Selecteer Leveringslogboek om het leveringslogboek te lezen: de totalen sinds het abonnement is aangemaakt, de dead letters met hun pogingen en laatste fout, en de tests die vanaf deze pagina zijn verstuurd. Test versturen staat ook in het dialoogvenster.

   (Groter weergeven)

   Grotere weergave sluiten

Bewerken wijzigt een abonnement; laat het geheim leeg om het opgeslagen geheim te behouden, en gebruik Webhook is ingeschakeld om leveringen te onderbreken. Verwijderen verwijdert het, en de dead letters gaan verloren; alarmen die naar zijn labels sturen, bereiken het niet meer.

Resultaat

Het abonnement staat in de lijst, de test toont Geleverd, en de ontvanger krijgt vanaf nu elke overeenkomende gebeurtenis.

Automatisering

Met de CLI

Het geheim komt uit de omgevingsvariabele KYVERNON_WEBHOOK_SECRET of uit --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 en --label kunnen worden herhaald. webhooks deliveries <id> toont de laatste 50 leveringen van een abonnement. webhooks list toont de tellers van elk abonnement, en webhooks delete <id> verwijdert er een. Om een levering in een shell te verifiëren, berekent u de handtekening over het tijdstempel, een punt en de body:

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

Met de API

POST /v1/webhooks maakt een abonnement aan met name, url, secret, eventTypes, labels, maxAttempts en tenant. GET /v1/webhooks toont ze, PUT /v1/webhooks/{id} wijzigt er een, POST /v1/webhooks/{id}/test verstuurt een test, GET /v1/webhooks/{id}/dead-letters leest de dead letters en DELETE /v1/webhooks/{id} verwijdert er een. De gRPC-service WebhookService biedt dezelfde bewerkingen.

GET /v1/webhooks/{id}/deliveries vraagt Kyvernon.Webhook.Manage. Het geeft de laatste 50 leveringen van het abonnement terug, de nieuwste eerst. Ze staan met het abonnement in de gerepliceerde store. Testleveringen worden ook gelogd. Elke levering heeft deze velden:

Opbouw van een levering

Elke levering is een POST met het inhoudstype application/cloudevents+json en deze headers:

Het CloudEvents-type is kyvernon.event.<event type>, bijvoorbeeld kyvernon.event.VmPoweredOffEvent, en data bevat de gebeurtenis zoals de API die toont. De dagelijkse verbruikssamenvatting heeft het type kyvernon.usage.daily_summary; abonneer u erop met het gebeurtenistype UsageDailySummary.

Verifieer een levering voordat u hem vertrouwt. Bereken de HMAC over het tijdstempel, een punt en de ruwe body, vergelijk die met de header in constante tijd en weiger een te oud tijdstempel. Een herhaalde levering draagt dezelfde gebeurtenis-id, dus een ontvanger kan duplicaten negeren.

Nieuwe pogingen en dead letters

Een levering slaagt wanneer de ontvanger binnen 10 seconden antwoordt met een status in het 2xx-bereik. Anders probeert Kyvernon het opnieuw met een vertraging die bij een seconde begint en verdubbelt tot 60 seconden, tot het aantal pogingen is bereikt. Kyvernon volgt geen omleidingen. Na de laatste poging wordt de gebeurtenis geparkeerd in de dead letters van het abonnement, met het aantal pogingen en de laatste fout, in een begrensde lijst. Herstel de ontvanger, stuur een test om te controleren of hij bereikbaar is, en gebruik de gebeurtenis-id's om de gebeurtenissen te vinden in de gebeurtenissenlijst.

Beperkte doelen

Kyvernon weigert een doel dat een loopback-, privé-, link-local-, gedeeld (carrier-grade NAT), multicast- of ander speciaal adres is, zodat een abonnement geen interne services kan bereiken. De controle draait wanneer u het abonnement aanmaakt en opnieuw bij elke levering, op de adressen waarnaar de hostnaam verwijst. De weigering is error.webhook.target_restricted. Wanneer de ontvanger bewust in uw eigen netwerk staat, vermeldt een beheerder dat netwerk, bijvoorbeeld 198.51.100.0/24, als toegestaan netwerk in de sectie [webhooks] van de controllerconfiguratie en herstart de controller. De configuratiereferentie bevat de sleutel.

Zie ook

• Gebeurtenissen toont de gebeurtenistypen.
• Alarmen leveren statuswijzigingen af per label.
• Verbruik beschrijft de dagelijkse samenvatting.