Webhooks API:er gör det möjligt för externa system att prenumerera på händelser i Inspera Assessment. Webhooks är baserade på händelseloggsystemet (Event Log) som används av Inspera Assessment-klienten, men med en begränsad uppsättning händelser som stöds för närvarande.

Allmänt

För både validering och händelseaviseringar skickas anropet som en HTTPS POST-begäran, med en standardtimeout på 10 sekunder. Om slutpunkten (endpoint) inte svarar med HTTP 200 OK anses begäran ha misslyckats och försöks igen. För valideringsbegäranden gör vi inga nya försök. För händelseaviseringar gör vi 3 försök innan vi ger upp.

Alla aviseringar innehåller en liten JSON-payload i ett fast format. Dessa innehåller grundläggande metadata men inkluderar inte omfattande data relaterade till händelsen. Detta görs för att säkerställa en konsekvent och kontrollerad storlek på payloaden. Till exempel: när du prenumererar på en händelse för slutförd bedömning innehåller aviseringen inte några betyg, utan endast information om objektet som händelsen gäller. Mer detaljerad information kan sedan hämtas via API:erna med hjälp av de identifierare som anges i webhook-payloaden.

Observera att aviseringar inte skickas ut till prenumerationer som är registrerade på samma användare som utlöste händelsen. Detta är i linje med hur aviseringar hanteras för andra aviseringstyper i Inspera, och görs för att undvika att användare överöses med aviseringar om sina egna handlingar i systemet.

Verifiering

För att verifiera att en händelse kom från Inspera och är en giltig händelse inkluderas en hash av meddelandekroppen i anropets header. Hashen är en HMAC SHA1 Hex av body-innehållet, genererad med hjälp av den "secret" som angavs när prenumerationen sattes upp. Hashen tillhandahålls i "X-Inspera-Signature".

Webhook API:er

/v1/subscription/events

Detta API listar alla händelsetyper för vilka Webhook-prenumerationer stöds.

/v1/subscription + /v1/subscription/{subscriptionId}

Dessa API:er gör det möjligt för anroparen att lista alla aktuella prenumerationer, registrera nya samt ta bort befintliga prenumerationer. När en prenumeration registreras valideras den angivna slutpunkten och måste svara med HTTP 200 OK vid anrop med en POST-begäran. Begäran måste svara inom standardtimeouten.

Observera att webhook-händelser endast skickas till användare som både är registrerade lyssnare av händelsen och där samma användare antingen är medverkande på det berörda provet, har skrivåtkomst till det berörda innehållet eller är en användaradministratör (beroende på objekttyp som påverkas av händelsen). Användare med utökad åtkomst får alla tillämpliga händelser, oavsett explicita behörigheter eller medverkanderoller på enskilda objekt.

Valideringsbegäran ser ut ungefär så här:

{
  contextObjectId: 0, 
  contextObjectTitle: d7e7a6dd-1c82-45ff-aea1-cbbbe9ce1bb0, 
  event: verification, 
  timestamp: 2018-10-04T16:44:30Z
}

Det finns ingen tidsbegränsning på livslängden för prenumeration på Inspera-händelser. När en prenumeration har gjorts löper den inte ut förrän användaren avbryter eller tar bort prenumerationen.

Det är möjligt att hämta listan över händelser användaren prenumererar på genom att anropa GET-metoden för slutpunkten /v1/subscription. Denna metod returnerar en matris (array) med alla händelser användaren prenumererar på med ytterligare information om varje hittad händelse.

Format

Payloaden för varje händelse följer samma generella format, där vissa fält är valfria.

Exempel

{
  "event": "qti_export_ready",
  "marketplaceId": 1357554,
  "contextObjectId": 74379551,
  "contextObjectType": "QUESTION_SET",
  "timestamp": "2021-06-29T18:16:06Z"
}

Extra info

Fältet extraInfo följer ett allmänt format, men detaljerna i de tillhandahållna värdena beror på den specifika händelsetypen.

Automatisk avregistrering (Auto-unsubscribe)

Även om det finns ett anrop för att avbryta prenumerationer på webhook-aviseringar som inte längre ska användas, har vi erfarit att vissa prenumerationer som skapats för testning bara överges när testningen är klar, vilket lämnar aviseringarna aktiva – även efter att slutpunkten har slutat fungera.
Eftersom detta faktiskt orsakar problem har vi skapat en funktion för att automatiskt avregistrera ”döda” prenumerationer.

Vi är naturligtvis medvetna om att en slutpunkt kan ha tillfälliga problem, och därför kontrollerar vi flera gånger innan vi faktiskt tar bort prenumerationen.

För närvarande skickar vi ett valideringsanrop var 8:e timme till varje registrerad slutpunkt (om två prenumerationer använder samma slutpunkt skickar vi bara ett meddelande). Om en slutpunkt misslyckas vid 3 påföljande anrop kommer alla prenumerationer till den slutpunkten att automatiskt avregistreras. Observera att denna funktion styrs av en konfigurerbar inställning och måste slås på för att börja avregistrera. Om ni vill ha detta, vänligen kontakta Service Desk.