Webhook-leverans

Totara skickar en HTTP POST till en webhooks-endpoint och förlitar sig på HTTP-svarskoden för att avgöra om en förfrågan var framgångsrik, felaktig eller kräver att skickas igen.

Framgångsrika förfrågningar

Totara anser att en webhook är framgångsrik när HTTP POST till webhooken svarar med en HTTP-kod i 200-intervallet. Totara kommer att uppdatera sändningstiden för framgångsrika webhooks och de kommer inte att skickas igen.

Felaktiga förfrågningar

Totara-webhooks anser att en förfrågan är felaktig när webbhookens endpoint svarar med en HTTP-kod i 400-intervallet. I detta fall kommer Totara att flytta webhook-nyttolasten till kön för döda brev (Se Webhook-dödsbokföring nedan). När ett objekt har flyttats till kön för döda brev, kommer Totara att upphöra med att försöka skicka om en förfrågan.

Misslyckade förfrågningar

Alla svar som Totara webhooks tar emot med en HTTP-kod som är utanför 200 och 400, kommer Totara att försöka skicka om. För mer information om försök att skicka om, se avsnittet Webhook-omtagningar nedan.

Webhook-omtagningar

Totara webhooks har inbyggda omtagningar. Vi kommer att försöka leverera en webhook-payload till webhooks endpoint upp till 10 gånger. Vid varje försök kommer vi att öka tiden som webhooken ligger i kön innan vi försöker skicka om (Backoff). Följande tabell visar försöket och den väntetid som är associerad innan vi försöker skicka om:

Om en webhook fortsätter att misslyckas med att markeras som lyckad (webhookens slutpunkt svarar inte med en HTTP-svarskod i 200-intervallet), kommer webhooks att flytta nyttolasten till dead letter-kön. Se Webhook dead lettering nedan för mer information om detta.

Webhook dead lettering

Totara har en standardkö som den läser igenom för att skicka ut webhook-nyttolaster. När en webhook misslyckas med att svara med ett lyckat svar efter 10 försök eller svarar med en HTTP-svarskod i 400-intervallet, kommer nyttolasten att flyttas till en dead letter-kö.

Kö för förlorade meddelanden innehåller information om webhook-payload och låter en administratör undersöka varför webhooken misslyckades med att skickas. Detta kan vara något så enkelt som att webhookens slutpunkt pekar på en felaktig URL.

Om en administratör vill försöka igen med en webhook-payload som har flyttats till kö för förlorade meddelanden, kan de göra det via ett CLI-script: totara/webhook/cli/webhook_requeue_dead_letter.php.

Detta script accepterar en ID-flagga, som motsvarar objektets ID i tabellen för kö för förlorade meddelanden totara_webhook_dlq_item.id.

När detta script körs kommer objektet att läggas tillbaka i den vanliga webhook-kön för att skickas om under nästa cron-körning. Försöket förblir dock detsamma, så om ett objekt redan har använt 10 försök och misslyckas igen, kommer objektet att hamna tillbaka i kö för förlorade meddelanden. Det finns inga begränsningar på hur många gånger en payload med förlorade meddelanden kan skickas om.

Livstid för webhook-payload

Alla förfrågningar till webhooks sparas i 14 dagar efter att webhooken har fått ett framgångsrikt svar från webhookens slutpunkt. Efter den tiden kommer ett schemalagt jobb att köras för att rensa loggarna. Alla objekt i dead letter-kön hålls i 28 dagar efter att innehållet lades till i dead letter-kön. Efter 28 dagar kommer ett separat schemalagt jobb att köra för att rensa dead letter-kön. Dessa jobb kan konfigureras med konfigurationsinställningar och justeras på samma sätt som vilket schemalagt jobb som helst kan.

Notera: Händelsedata kan innehålla personligt identifierbar information (PII) om användare inom systemet.

De ovan nämnda rensningsjobben kommer att hantera att ta bort dessa data efter 14 dagar för loggfilerna och 28 dagar för dead letter-kön.

Om kortare tidsramar krävs för att uppfylla GDPR:s krav på dataradering kan dessa tidsramar justeras via följande konfigurationsinställningar:

$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

]

Innehållssignering

Webhooks kommer med innehållssignering som ett sätt att verifiera att en inkommande begäran har kommit direkt från Totara och att data inte har manipulerats. När du skapar en webhook kommer en hemlighet att genereras automatiskt.

Hemligheten kan växlas med hjälp av ‘Visa/Dölj’-knappen på kontrollen. Hemligheten och själva begäran används när en webhook-belastning skickas till en webbhooks-slutpunkt. En Hash-baserad meddelandeautentiseringskod (HMAC) som använder sha256-algoritmen kommer att skapas och läggas till i begärans header X-Totara-Signature.

Verifiera signaturen

Du kan jämföra en signatur i PHP med följande kodsnutt:

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

CLI-skript för att verifiera signatur

Webhooks kommer också med ett CLI-skript för att verifiera X-Totara-Signature. Skriptet kan hittas på: server/totara/webhook/cli/webhook_verify_signature.php

För att köra skriptet anger du helt enkelt följande flaggor:

T.ex.

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

Notera: Klicka på ‘Rotera’ kommer att ersätta webhookens befintliga hemlighet; alla förfrågningar som för närvarande är köade för att skickas kommer att använda denna nya hemlighet.

Prestandahänsyn

Webhooks reagerar på händelser som sker i Totara. Av denna anledning måste det finnas en balans mellan antalet webhooks en webbplats har i förhållande till antalet händelser en webhook är prenumererad på. Vi rekommenderar att hålla sig till att antingen ha färre webhooks prenumererade på flera händelser eller flera webhooks prenumererade på färre händelser.

Webhooks kommer som standard att ställa in sig själva för att schemaläggas så att de köas och behandlas med de schemalagda jobben. Om du har många webhooks inställda för omedelbar sändning, kommer de att avbryta användaren när händelsen utlöses och kan få sidan att kännas trög. Vi rekommenderar att hålla sig till det schemalagda läget.