Webhooks

Het belangrijkste verschil tussen de API en webhooks is de mate van proactiviteit. Met een API haal je als instelling zelf de data uit Ans op, waarbij je zelf verantwoordelijk bent voor de timing van de verzoeken om de data te verkrijgen. Een webhook daarentegen stelt je in staat om proactief het moment te bepalen waarop je de data uit Ans ontvangt. Met een webhook kun je realtime data-uitwisseling realiseren tussen Ans en andere platforms. Dit wordt hieronder met een voorbeeld toegelicht.

Wanneer je bijvoorbeeld gegevens over resultaten uit Ans wilt halen om deze te importeren in je studentinformatiesysteem, dan kun je de API gebruiken om deze informatie te verkrijgen. Een van de mogelijke requests die je via de API kunt doen is een GET Results request van een specifieke toets. Ans geeft alle beschikbare resultaten. Maar op welk moment doe je zo'n request? Wellicht heeft een docent nog niet alle resultaten volledig nagekeken? Indien je dit via de API doet, dan moet je vervolgens nog controleren of alle resultaten zijn nagekeken.

Bij het gebruik van de webhook functionaliteit wordt je door Ans geïnformeerd over specifieke veranderingen, exact op het moment dat de verandering ook wordt doorgevoerd. Het is mogelijk om een webhook te activeren die luistert naar alle veranderingen die gedaan worden op objecten in Ans, zoals resultaten. De webhook stuurt een bericht met de informatie die is gewijzigd. Je kunt bijvoorbeeld je docenten de beoordelingsfunctie laten gebruiken als ze klaar zijn met het nakijken van een student. Wanneer een student nagekeken is, kan de docent met behulp van de beoordeling het resultaat goedkeuren of afkeuren. Op het moment dat de beoordeling wordt gedaan, wordt de webhook geactiveerd. Hierbij wordt je proactief geïnformeerd over een resultaat dat klaar is om naar een ander platform te worden gestuurd.

Je kunt ook de webhook gebruiken om een activatie van een ander proces te starten, zowel binnen als buiten Ans. Zo kun je bijvoorbeeld een publicatie voor een toets openzetten zodra alle resultaten van een toets zijn nagekeken. Andere processen zijn ook mogelijk.

Op dit moment zijn webhooks beschikbaar voor de volgende objecten in Ans:

• Assignment (toets)
• Question bank assignment (itembanktoets)
• Result (resultaat)
• User (gebruiker)

Ans ondersteunt alleen de Engelstalige benamingen van de objecten in de webhook.

De volgende events kunnen ingesteld worden in de webhook:

• Create (aanmaken)
• Update (wijzigen)
• Delete (verwijderen)
• All events (alle hierboven genoemde events)

Ans stelt verschillende events beschikbaar waar je naar kunt luisteren. Hierbij kun je naar alle events luisteren, naar alle events voor een specifiek object of naar een event van een object.

• Alle events: gebruik '*' om naar alle events van alle objecten te luisteren.
• Alle events voor een object: gebruik de naam van het object, bijvoorbeeld 'assignment', om te luisteren naar alle events van dat object.
• Een event voor een object: combineer een object met de naam van het event om te luisteren naar die specifieke combinatie, bijvoorbeeld 'assignment.update'.

Om een nieuw webhook endpoint te maken, volg de onderstaande stappen.

1. Klik op het account_circle -icoon aan de rechterbovenkant.
2. Selecteer settings Instellingen. 
3. Klik op Webhooks in het menu aan de linkerkant.
4. Klik op Nieuwe webhook.
5. Vul het Url* veld in.
   • Het URL veld wordt gebruikt voor een webpagina waar de informatie van de webhook naar toe gestuurd wordt. Zoals hierboven aangegeven adviseert Ans om de webhook in combinatie met de API te gebruiken. Je kunt hier bijvoorbeeld een locatie van de enterprise service bus van je school beschrijven.
6. Vul het Abonnementen* veld in.
   • Het abonnementen veld is de combinatie van objecten en events waar de webhook naar moet luisteren.
7. Klik op het dropdown menu om de API versie* te selecteren.
8. Klik op Aanmaken. 

Events

Zodra je webhook is aangemaakt, klik je op de URL om naar het tabblad Events te navigeren. Vanaf hier worden alle events weergegeven die de webhook hebben geactiveerd. Webhook-events worden 14 dagen opgeslagen. Je kunt op een event klikken om de inhoud te bekijken. Een event bestaat uit het volgende:

• Tijdstip: Het moment waarop het event wordt geactiveerd.
• Gebeurtenis: Beschrijft het event dat heeft plaatsgevonden op het object.
• Respons: De status van de levering. In het voorbeeld wordt een nep-URL gebruikt. Daarom staat de response gepland voor levering. Onder het tabblad 'Event' zie je ook een dropdown waarmee je kunt filteren op responses die zijn geslaagd of mislukt.
• Acties: Hier vind je de knop 'Resend'. Als je hierop klikt, wordt de webhook opnieuw verzonden.

Als je op een webhook-event klikt in de tabel op het tabblad Events, verschijnt er een popup waarin je ook het volgende ziet.

• Payload veranderingen: Een overzicht van alle wijzigingen in het object. In dit geval is de naam van de toets gewijzigd van 'abc' naar 'abcdef'. Het kan voorkomen dat hier meerdere wijzigingen zichtbaar zijn.
• Payload: In dit veld is een overzicht zichtbaar van het object met de meest actuele informatie. Zoals je kunt zien, is de naam van de toets hier gewijzigd.

Al onze verzoeken worden verzonden vanaf het vaste IP-adres 3.248.46.102. 

Webhook instellingen

Naast het tabblad Events zie je het tabblad Webhook instellingen. Vanuit dit overzicht kun je de URL, de subscriptions en de API-versie wijzigen. Je kunt de webhook ook in- of uitschakelen of het webhook-endpoint verwijderen indien nodig.