Webhook levering

Totara verzendt een HTTP-bericht naar een webhooks-eindpunt en vertrouwt op de HTTP-responscode om te beslissen of een verzoek succesvol, slecht of opnieuw moet worden verzonden.

Succesvolle aanvragen

Totara acht een webhook succesvol wanneer de HTTP POST op de webhook reageert met een HTTP-code in het bereik van 200. Totara zal de tijd die verzonden wordt van geslaagde webhooks aanpassen en ze zullen niet meer verzonden worden.

Foute verzoeken

Totara webhooks beschouwt een fout verzoek wanneer het eindpunt van de webhook reageert met een HTTP-code in het bereik van 400. In dit geval zal Totara het laadvermogen van de webhook naar de wachtrij voor dode letters verplaatsen (zie Webhook dood-belettering hieronder). Zodra een onderdeel naar de wachtrij met dode letters is verplaatst, zal Totara stoppen met het opnieuw verzenden van een verzoek.

Niet-geslaagde aanvragen

Elk antwoord dat Totara webhooks ontvangt met een HTTP-code die buiten 200 en 400 ligt, zal Totara proberen opnieuw te verzenden. Voor meer details over nieuwe pogingen, zie de Webhook-pogingen sectie hieronder.

Webhook-pogingen

Totara webhooks worden geleverd met ingebouwde nieuwe pogingen. We zullen proberen om maximaal 10 keer een webhook-lading te leveren aan het webhooks-eindpunt. Bij elke poging verlengen we de tijd dat de webhook in de wachtrij staat voor we opnieuw proberen te verzenden (Backoff). De volgende tabel toont de poging en de bijbehorende wachttijd voor we opnieuw proberen te verzenden:

Als een webhook nog steeds niet als succesvol wordt gemarkeerd (het eindpunt van de webhook reageert niet met een HTTP-responscode in het bereik van 200), verplaatst webhook het laadvermogen naar de wachtrij met lege letters. Zie Webhook doodlopende belettering hieronder voor meer informatie hierover.

Webhook dode belettering

Totara heeft een standaardwachtrij die het doorleest om webhook-ladingen te verzenden. Wanneer een webhook na 10 pogingen niet reageert met een succesvol antwoord of reageert met een HTTP-antwoord in het bereik van 400, wordt het laadvermogen verplaatst naar een wachtrij met lege letters.

De wachtrij met dode letters bevat details over het laadvermogen van de webhook en stelt een beheerder in staat om te onderzoeken waarom de webhook niet heeft verzonden. Dit zou iets eenvoudigs kunnen zijn als het webhooks eindpunt naar een foute URL wijst.

Als een beheerder een webhook-lading die naar de wachtrij voor dode letters is verplaatst, opnieuw wil proberen, kan deze dit doen via een CLI-script: totara/webhook/cli/webhook_requeue_dead_letter.php.

Dit script accepteert een ID-vlag, die overeenkomt met de ID van het onderdeel in de dode letter wachtrijtabel totara_webhook_dlq_item.id.

Wanneer dit script wordt aangeroepen, wordt het onderdeel teruggeduwd naar de standaard webhook-wachtrij om opnieuw te worden verzonden tijdens de volgende cron-run. De poging blijft echter hetzelfde, dus als een onderdeel al 10 pogingen heeft opgebruikt en opnieuw mislukt, komt het onderdeel terug in de wachtrij met lege letters. Er zijn geen beperkingen op het aantal keer dat een leeg laadvermogen opnieuw in de rij kan worden geplaatst.

Levensduur webhook-lading

Alle verzoeken aan webhooks worden 14 dagen bewaard nadat de webhook een succesvol antwoord heeft ontvangen van het eindpunt van de webhook. Na die tijd wordt een geplande taak uitgevoerd om de logs op te schonen. Alle onderdelen in de wachtrij met lege letters worden 28 dagen bewaard nadat het laadvermogen is toegevoegd aan de wachtrij met lege letters. Na 28 dagen zal er een aparte geplande taak worden uitgevoerd om de wachtrij met lege letters op te schonen. Deze taken kunnen worden geconfigureerd met configuratie-instellingen en op dezelfde manier worden aangepast als elke geplande taak.

Als deze optie niet wordt geactiveerd, blijft de oude 'blader'-opmaak behouden. Gebeurtenisgegevens kunnen Persoonlijk identificeerbare informatie (PII) bevatten over gebruikers binnen het systeem.

De bovenstaande opschoningstaken zullen het verwijderen van deze gegevens na 14 dagen voor de logs en 28 dagen voor de wachtrij met lege letters verwerken.

Als er kortere tijdslimieten nodig zijn om te voldoen aan de verplichtingen voor het verwijderen van gegevens van de AVG, kunnen deze tijdslimieten worden aangepast via de volgende configuratie-instellingen:

$CFG->forced_plugin_settings['totara_webhook'] = [

  'queue_purge_threshold' => (30  24  60 * 60) // given in number of seconds - default 30 days

  'dead_letter_purge_threshold' => (60  24  60 * 60) // given in number of seconds - default 60 days

]

Laadbelasting ondertekenen

Webhooks worden geleverd met het ondertekenen van het laadvermogen als een manier om te verifiëren dat een inkomend verzoek rechtstreeks van Totara afkomstig is en dat er niet met de gegevens is geknoeid. Wanneer je een webhook maakt, wordt er automatisch een geheim gegenereerd.

Het geheim kan worden omgewisseld met de knop 'Toon/verberg' op de bediening. Het geheim en de hoofdtekst van het verzoek wordt gebruikt wanneer een webhook-lading naar een webhooks-eindpunt wordt verzonden. Een Hash-gebaseerde berichtauthenticatiecode (HMAC) die het sha256-algoritme gebruikt, wordt gemaakt en toegevoegd in de aanvraagkop X-Totara-Signature.

Handtekening verifiëren

Je kunt een handtekening in PHP vergelijken met de volgende code snippet:

$calculated_signature = hash_hmac(
    'sha256',
    $body,
    $secret
);
if (hash_equals($signature_to_verify, $calculated_signature)) {
    $message = "Signature verified";
}

CLI-script om handtekening te verifiëren

Webhooks wordt ook geleverd met een CLI-script om het script te verifiëren. X-Totara-Signature. Het script kan gevonden worden op: server/totara/webhook/cli/webhook_verify_signature.php

Om het script uit te voeren, geef je de volgende markeringen:

Bijvoorbeeld

$ sudo -u www-data /usr/bin/php totara/webhook/cli/webhook_verify_signature.php --signatu

Als deze optie niet wordt geactiveerd, blijft de oude 'blader'-opmaak behouden. Als je op 'Draai' klikt, wordt het bestaande geheim van de webhook vervangen. Alle verzoeken die momenteel in de wachtrij staan om te verzenden, gebruiken dit nieuwe geheim.

Performance-overwegingen

Webhooks reageren op gebeurtenissen in Totara. Om deze reden moet er een evenwicht zijn tussen het aantal webhooks dat een site heeft en het aantal gebeurtenissen waarop een webhook is ingeschreven. We raden aan om ofwel minder webhooks te hebben ingeschreven op meerdere uitvoeringen of meerdere webhooks te hebben ingeschreven op minder uitvoeringen.

Webhooks zullen zichzelf standaard zo instellen dat ze in de wachtrij geplaatst worden en verwerkt worden met de geplande taken. Als je veel webhooks hebt ingesteld met onmiddellijke verzending, zullen ze de gebruiker onderbreken wanneer de gebeurtenis wordt geactiveerd en kunnen ze ervoor zorgen dat de pagina traag aanvoelt. We raden aan om de geplande instelling te volgen.