Achtergrond
Door middel van een Webhook kan assessmentQ externe platformen voorzien van real-time informatie.
assessmentQ biedt de volgende Webhooks:
Sessie beëindigd
Opdrachtresultaten gepubliceerd
Wanneer u een abonnement op (één van) deze Webhooks instelt, levert assessmentQ onmiddellijk een bericht aan het externe platform wanneer de verwachte gebeurtenis zich heeft voorgedaan, bijvoorbeeld wanneer een nieuwe sessie is beëindigd of wanneer er nieuwe resultaten voor een opdracht beschikbaar zijn.
Als beheerder kunt u zich abonneren op de assessmentQ Webhooks via de module Integraties.
Opmerking: Abonneren op de assessmentQ Webhooks wordt ook ondersteund via de assessmentQ API.
Abonneren op een Webhook
Ga als volgt te werk om een abonnement op een Webhook te nemen:
Open de module Integraties in Instellingen.
Resultaat: Het overzicht van Webhook abonnementen wordt getoond.Klik op de knop Toevoegen in de rechterbovenhoek.
Resultaat: De popup Webhook abonnement toevoegen wordt getoond.Voer een naam in voor uw abonnement.
Opmerking: In het geval dat u zich abonneert op de Opdrachtresultaten gepubliceerd Webhook, wordt de naam van het abonnement getoond in de module Opdrachtrapporten wanneer u de optie Resultaten verzenden selecteert.
Selecteer de gebeurtenis waarop u zich wilt abonneren.
Voer de URL in waarnaar de gegevens worden verzonden wanneer de Webhook wordt getriggerd.
Klik op Opslaan.
Resultaat: Het overzicht van het Webhook-abonnement wordt bijgewerkt. Als u geabonneerd bent op de Sessie beëindigd Webhook, wordt een bericht verzonden zodra een deelnemer in een sessie op de knop Voltooien klikt. Als u zich hebt geabonneerd op de Webhook Opdrachtresultaten gepubliceerd, wordt een bericht verzonden zodra een analist klikt op Resultaten verzenden voor een opdracht in de module Opdrachtrapporten.
Abonneren via de assessmentQ API
Gelijkaardig aan het abonneren via de backoffice, kan u ook abonneren via onze API met volgende API aanroep:
POST /v2/subscriptions
In de body moet u volgende data voorzien:
Een naam voor de webhook
Welke events u op wilt abonneren
De URL die moet opgeroepen worden
De veiligheidssleutel die gebruikt zal worden
Deze laatste optie, de veiligheidssleutel, is niet beschikbaar via onze assessmentQ backoffice. Deze veiligheidssleutel maakt het mogelijk om nog een extra bescherming toe te voegen tegen een Man-In-The-Middle aanval. Als deze veiligheidssleutel wordt meegegeven, zal assessmentQ een header "X-Hook-Signature" toevoegen aan elke aanroep van de webhook met een bepaalde waarde. Deze waarde wordt berekend door de payload van de aanroep te hashen volgens het HMACSHA256 algoritme, met de gegeven veiligheidssleutel als encryptiesleutel.
Bijvoorbeeld: Een webhook voor een beëindigde sessie met volgende payload
SessionId = 123
en veiligheidssleutel "abc" zal resulteren in een "X-Hook-Signature" met als inhoud
"17c5577856d43d0d2abbf6f6530b46f8093ce1f30be862919febdb7b49d61d7b".
Bevestigen van het abonnement
Wanneer u abonneert op een assessmentQ webhook zal assessmentQ een bevestiging vragen. De registratie van de webhook zal enkel voltooid zijn na deze bevestiging. Als bevestiging stuurt assessmentQ een testaanroep naar de gegeven URL. Deze testaanroep is een POST aanroep met een lege body en optioneel een "X-Hook-Secret" header.
Om uw webhook te valideren, moet de respons een NoContent (HTTP 204) respons zijn die dezelfde header en inhoud gebruikt als de aanroep. Dat betekent dat als de testaanroep een "X-Hook-Secret" header gebruikt met waarde "abc123", uw respons dit ook dient te bevatten.
Als u een HTTP 422 BadEntity respons ontvangt wanneer u een webhook probeert toe te voegen, betekent dit dat de opgegeven URL niet de gewenste respons gaf op de testaanroep. Het toevoegen van de webhook zal hierop falen en de webhook zal niet worden geregistreerd.