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)
• 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 de URL en het Subscriptions velden in en klik op Bewaren.
   • 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.
   • Het subscriptions veld is de combinatie van objecten en events waar de webhook naar moet luisteren, zoals hierboven beschreven.

Zodra je de webhook aangemaakt hebt, kun je op de URL klikken van de webhook. Daarna kun je op Webhook instellingen klikken in het menu aan de rechterkant. In het voorbeeld dat hieronder is gegeven, is een webhook gemaakt die luistert naar alle events van een assignment. Zoals je in de onderstaande afbeelding kunt zien kan de webhook in- en uitgeschakeld worden. Daarnaast kan de webhook verwijderd worden.

Om te zien hoe een event eruit ziet, klik op Event in het menu aan de rechterkant. In dit menu zie je een overzicht van alle events die geactiveerd zijn door de webhook. Webhook events worden 14 dagen opgeslagen. Je kunt op een event klikken om de inhoud te bekijken. Zoals in het onderstaande screenshot te zien is, bestaat een event uit de volgende onderdelen:

• Tijd: Het moment waarop het event geactiveerd werd. 
• Response: De afleveringsstatus. In het voorbeeld is een nep URL gebruikt. Daarom is de afleveringsstatus bezig met versturen.
• Payload changes: Het overzicht van de wijzigingen in het object. In dit geval is de naam van de toets gewijzigd van 'abc' naar 'abcdef'. Het kan voorkomen dat meerdere wijzigingen hier zichtbaar zijn.
• Payload: In dit veld wordt het overzicht van het object met de meest actuele informatie zichtbaar gemaakt. Zoals je kunt zien is de naam van de toets in dit geval gewijzigd.

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