TABLE OF CONTENTS


Om de zelfredzaamheid van onze klanten te vergroten, zijn we het afgelopen kwartaal begonnen met de ontwikkeling van API’s en Webhooks (standaard koppelvlakken). 


1. Wat zijn API's en Webhooks?

Met API's en Webhooks kunnen externe systemen of applicaties informatie vanuit de Xpert Suite ophalen en aanleveren en kunnen acties binnen de Xpert Suite worden geïnitieerd. 


Hiermee wordt het mogelijk om eigen applicaties te ontwikkelen of bestaande applicaties te koppelen aan de Xpert Suite. Er kunnen bijvoorbeeld eigen HR- of klantportalen geïntegreerd worden, maar ook kan eigen software ontwikkeld worden voor het afhandelen van een taak buiten de Xpert Suite-software, maar voor gebruikers gewoon direct bereikbaar vanuit de Xpert Suite. Tot nu toe kon dit alleen voor applicaties waar wij al een integratie voor ontwikkeld hadden. Maar als er genoeg API’s beschikbaar zijn, dan kunnen klanten dit dus volledig onafhankelijk van Otherside at Work realiseren.


Ook voor het ‘automatiseren van de eigen processen’ kan dit verregaand gebruikt worden. Externe ‘Robotic Process Automation’-tools zoals Zapier, ‘If This Then That’ of Microsoft Flow kunnen hierdoor stabiel geïntegreerd worden.


Samenvattend geven de API’s die ontwikkeld gaan worden de mogelijkheid om volledig zelfstandig (dus zonder een werkopdracht of maatwerkverzoek naar Otherside):

  1. De Xpert Suite te integreren in eigen portalen;
  2. Vanuit de Xpert Suite te integreren met eigen sub-portalen;
  3. Eigen maatwerksoftware aan te sluiten op de Xpert Suite voor optimalisatie van sub-processen;
  4. Automatisering van herhalende klikacties m.b.v. RPA-tools;
  5. Ontwikkeling van eigen realtime-gegevensuitwisseling met andere applicaties (pushberichten i.p.v. periodieke gegevensuitwisseling).


2. Beheer van API-Accounts

Om gebruik te kunnen maken van deze API’s dient voor de externe applicatie een API-account aangemaakt te worden, waarmee de autorisaties van het externe systeem kunnen worden beheerd. Om deze reden kunnen API-accounts ook niet inloggen zoals ‘normale’ gebruikers. Wél hebben deze accounts – net als gebruikers – bepaalde autorisaties, die gelden voor alle acties die het account kan uitvoeren via onze API’s. Het is nu mogelijk om API-accounts te beheren binnen het gebruikersbeheer op dezelfde manier als ‘normale’ gebruikers in het gebruikersbeheer.


 

Bij het aanmaken van een API-account word er een wachtwoord (API-token) en een TOTP-secret gegenereerd. Bewaar deze goed! Voeg dit TOTP-secret toe aan een authenticator om de TOTP-code te ontvangen die je nodig hebt om in te loggen.   

2.1 Gebruik van API’s

Een overzicht van de API’s die momenteel beschikbaar zijn vind je via https://api.xpertsuite.app/. In dit overzicht staan ook de URL's die je doorverwijzen naar de swagger pagina van de API’s. Op deze pagina kan er gevonden worden wat er allemaal via een API-call gecommuniceerd word.

Met een service user kan je niet direct inloggen via het normale inlogscherm. Service users kunnen alleen inloggen via de API. 

Als je inlogt met een API-account krijg je een base URL terug. Dit endpoint moet je gebruiken om een request naar de API’s te doen.

Note: het API-account moet wel de autorisatie hebben om desbetreffende acties uit te voeren.


2.2 Impersonation

Het is mogelijk om via een API-call impersonation toe te passen op een gebruiker via een API-account. De acties die uitgevoerd zijn binnen de Xpert Suite zullen dan namens de gebruiker zijn die impersonated is. Impersonation is mogelijk via de OAuth2 standaard.


3. Webhooks

Een tweede belangrijke bouwsteen om goed te kunnen integreren is de mogelijkheid om op de hoogte te worden gebracht van wijzigingen in de Xpert Suite met actieve push-notificaties. Het periodiek opvragen van gegevens om zelf vast te stellen of er iets is gewijzigd, is hierdoor niet meer nodig. Om dit te ondersteunen introduceren we in de Xpert Suite ‘webhooks’. Hiermee kun je berichten naar je eigen software laten sturen bij specifieke events (of gebeurtenissen). De API’s kunnen vervolgens gebruikt worden om de gewenste details uit te lezen en de vervolgacties in de eigen applicatie te ondersteunen.

Voor superbeheerders zal een nieuwe link naar ‘Webhooks’ zichtbaar zijn onder Beheer > Koppelvlakken. Op dit moment is de hoeveelheid mogelijke webhooks nog beperkt, maar dit zal de komende periode sterk uitgebreid worden.



3.1 Ontvangers toevoegen

 

Bij het toevoegen van een ontvanger is het mogelijk om de URL op te geven waar de webhook naartoe gestuurd wordt.


In Topics registreer je voor welke events je webhooks wilt ontvangen.
 Wanneer je bijvoorbeeld Accounts.Update geselecteerd hebt krijg je webhooks wanneer er een gebruiker gewijzigd is.


In de Gebruiker selectie selecteer je een API-gebruiker die in principe de webhooks "ontvangt".
Wanneer er een webhook verstuurd wordt wordt er gecheckt of de geselecteerde gebruiker de juiste autorisaties heeft om de webhook te ontvangen.
De geselecteerde gebruiker ontvangt dus bijvoorbeeld geen webhooks van gebruikers waarvoor hij niet geautoriseerd is om ze te zien.


In Authenticatie protocol selecteer je de authenticatie van een webhook.
WebSub: Hierbij wordt er bij de webhook een "x-hub-signature" header meegestuurd met de HMAC van de request body en de opgegeven WebSub Secret.
OAuth2: Hierbij wordt er voordat de webhook verstuurd wordt een OAuth2 request gedaan naar de opgegeven OAuth2 url en wordt de teruggegeven access_token gebruikt in de "Authorization" header.
 

3.1 Ontvangers verwijderen

Het is mogelijk om ontvangers te verwijderen, hierna ontvangt deze ontvanger geen webhooks meer.
De verwijderde ontvangers zijn nog wel te zien in het overzicht en is het nog mogelijk om de verstuurde webhooks terug te zien.


3.2 webhook log

Hier is het mogelijk om de verstuurde webhooks terug te zien.
Op elke regel is het Id van de webhook te zien. Daarnaast is het betreffende topic van de webhook te zien, de status en welke statuscode er is ontvangen bij het versturen van de webhook. Daarnaast kan je ook de requestbody openen die de gegevens bevatten die verstuurd zijn. 


Wanneer er een webhook mislukt wordt deze een aantal keer opnieuw geprobeerd naar aanleiding van deze tabel:

 

Aantal retries

Mininum interval na laatste webhook

1

1 uur

2

2 uur

3

6 uur

4

24 uur

> 4

Niet