TABLE OF CONTENTS

• 1. Wat zijn API's en Webhooks?
• 2. Beheer van API-Accounts
  • 2.1 Gebruik van API’s
  • 2.2 Impersonation
• 3. Webhooks
  • 3.1 Ontvangers toevoegen
  • 3.1 Ontvangers verwijderen
  • 3.2 webhook log

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.

Het TOTP secret vind je bij het API account onder de two factor authenticatie:

Bij het instellen van de authenticatie app krijg je dan de TOTP sleutel te zien welke je nodig hebt om verbinding te kunnen maken:

2.1 Gebruik van API’s

Een overzicht van de API’s die momenteel beschikbaar zijn vind je via https://api01.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. 

• We volgen grotendeels de OAuth2 standaard
• De enige uitzondering is dat na het wachtwoord ook nog het TOTP code moet worden toegevoegd
• De loginURL voor service users is https://login.xpertsuite.app/services/api/oauth2

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.

2.3 Verbinden met de API

Wij krijgen met regelmaat de vraag over hoe er correct verbonden moet worden met de externe API.

Hieronder hebben wij een snippet toegevoegd met daarin een correct voorbeeld van hoe deze authenticatie werkt. 

using System;
using RestSharp;        // From https://www.nuget.org/packages/RestSharp 
using TwoFactorAuthNet; // From https://www.nuget.org/packages/TwoFactorAuth.Net

internal class Program
{
  static void Main()
  {
    var username = "apiuser.example";
    var clientSecret = "00000000-0000-0000-0000-000000000000";
    var totpSecret = "IGLIAHAEIXXQX6O2";

    var totpToken = new TwoFactorAuth().GetCode(totpSecret);
    var client = new RestClient("https://login.xpertsuite.nl");
    var request = new RestRequest("/services/api/oauth2", Method.Post);
    request.AddParameter("grant_type", "client_credentials");
    request.AddParameter("client_id", username);
    request.AddParameter("client_secret", clientSecret + totpToken);
    request.RequestFormat = DataFormat.Json;

    var response = client.Execute(request);
    Console.WriteLine($"Status: {response.StatusCode}");
    Console.WriteLine(response.Content);
    Console.ReadLine();
  }
}

Wanneer er een API wordt aangeroepen wordt per e-mail teruggekoppeld of de aanroep goed is gegaan. In deze e-mail wordt ook aangegeven om welke koppelingenaccount het gaat.  

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: