Webhooks API-ene lar eksterne systemer abonnere på hendelser i Inspera Assessment. Webhooks er basert på hendelsesloggsystemet (Event Log) som brukes av Inspera Assessment-klienten, men med et begrenset utvalg av hendelser som støttes for øyeblikket.

Generelt

For både validering og hendelsesvarsler sendes forespørselen som en HTTPS POST-forespørsel, med et standard tidsavbrudd (timeout) på 10 sekunder. Hvis endepunktet ikke svarer med HTTP 200 OK, anses forespørselen som mislykket og blir forsøkt på nytt. For valideringsforespørsler prøver vi ikke på nytt. For hendelsesvarsler prøver vi 3 ganger før vi gir opp.

Alle varsler inkluderer en liten JSON-payload i et fast format. Disse inneholder grunnleggende metadata, men inkluderer ikke omfattende data relatert til hendelsen. Dette gjøres for å sikre en konsistent og kontrollert størrelse på payloaden. For eksempel: når du abonnerer på en hendelse for fullført vurdering, inneholder ikke varselet selve karakterene, kun informasjon om objektet hendelsen gjelder for. Mer detaljert informasjon kan deretter hentes via API-ene ved å bruke identifiktatorene som er oppgitt i webhook-payloaden.

Merk at varsler ikke vil bli sendt til abonnementer som er registrert på samme bruker som utløste hendelsen. Dette er i samsvar med hvordan andre varslingstyper håndteres i Inspera, og gjøres for å unngå at brukere overøses med varsler om sine egne handlinger i systemet.

Verifisering

For å kunne verifisere at en hendelse kom fra Inspera og er en gyldig hendelse, inkluderes en hash av meldingsteksten i headeren på forespørselen. Hashen er en HMAC SHA1 Hex av bodyen, generert ved hjelp av "secret"-verdien som ble oppgitt da abonnementet ble satt opp. Hashen finnes i "X-Inspera-Signature".

Webhook API-er

/v1/subscription/events

Dette API-et lister opp alle hendelsestyper som støtter Webhook-abonnement.

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

Disse API-ene lar kaller liste opp alle nåværende abonnementer, registrere nye, samt slette eksisterende abonnementer. Ved registrering av et abonnement blir det oppgitte endepunktet validert, og det må svare med HTTP 200 OK når det kalles med en POST-forespørsel. Forespørselen må svare innenfor standard tidsavbrudd.

Merk at webhook-hendelser kun sendes til brukere som både er registrert som lyttere for hendelsen, og der samme bruker enten er bidragsyter på den berørte prøven, har skrivetilgang til det berørte innholdet, eller er brukeradministrator (avhengig av objekttypen hendelsen gjelder). Brukere med utvidet tilgang mottar alle relevante hendelser, uavhengig av eksplisitte tillatelser eller bidragsyterroller på enkeltobjekter.

Valideringsforespørselen ser omtrent slik ut:

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

Det er ingen tidsbegrensning på levetiden for abonnement på Inspera-hendelser. Når et abonnement er opprettet, utløper det ikke før brukeren melder seg av eller sletter abonnementet.

Det er mulig å hente listen over hendelser brukeren abonnerer på ved å bruke GET-metoden for endepunktet /v1/subscription. Denne metoden returnerer en matrise (array) over alle hendelser brukeren abonnerer på, med tilleggsinformasjon om hver hendelse.

Format

Payloaden i hver hendelse følger samme generelle format, der enkelte felt er valgfrie.

Eksempel

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

Tilleggsinformasjon (Extra info)

Feltet extraInfo følger et generelt format, men detaljene i verdiene avhenger av den spesifikke hendelsestypen.

Automatisk avmelding (Auto-unsubscribe)

Selv om det finnes et kall for å melde seg av webhook-varsler som ikke lenger skal brukes, har vi erfart at enkelte abonnementer opprettet for testing bare blir forlatt, slik at varslene forblir aktive – også etter at endepunktet har sluttet å fungere.
Siden dette utgjør et problem, har vi laget en funksjon for automatisk avmelding av "døde" abonnementer.

Vi anerkjenner naturligvis at et endepunkt kan ha midlertidige problemer, og derfor sjekker vi flere ganger før vi faktisk sletter abonnementet.

For øyeblikket sender vi et valideringskall hver 8. time til hvert registrerte endepunkt (hvis to abonnementer bruker samme endepunkt, sender vi bare én melding). Hvis et endepunkt feiler på 3 påfølgende kall, vil alle abonnementer til det endepunktet automatisk bli slettet. Merk at denne funksjonen styres av en konfigurerbar innstilling og må aktiveres for å starte automatisk avmelding. Hvis du ønsker dette, vennligst kontakt Service Desk.