Aanbevelingen Notificeren

Deze pagina is onderdeel van de Architectuur Notificeren in het Federatief Datastelsel. Het bevat een aantal aanbevelingen voor het op professionele wijze omgaan met notificaties. Ze zijn voor een deel gebaseerd op de architectuur die eerder is opgesteld in het VNG project Notificatieservices. Er is een separate pagina met richtlijnen voor het creëren van afleverbetrouwbaarheid met API's.

Communiceer asynchroon tussen publisher en consumersbewerken

Bij notificatieprocessen binnen een gedistribueerd en heterogeen landschap is het belangrijk dat organisaties en applicaties zoveel mogelijk van elkaar ontkoppeld zijn en onafhankelijk kunnen functioneren. Bij notificeren hoeven niet alle betrokken applicaties gelijktijdig actief te zijn. Dit vereist een vorm van ‘bufferen’ waarbij de producer geen onmiddellijk antwoord nodig heeft.

Gebruik het publish-subscribe patroonbewerken

Dit is een bekend, bewezen en vaak toegepast patroon voor notificeren. Het ontkoppelt providers en consumers van elkaar en maakt het mogelijk een onbeperkt aantal consumers te ondersteunen. Het wordt breed ondersteund door frameworks en event brokers. De inzet van een intermediary zoals een eventbroker ligt daarmee voor de hand.

Zorg dat de producer of intermediair het tempo waarin notificaties worden verstrekt kan aanpassen aan de mogelijkheden van consumersbewerken

Consumers zijn mogelijk niet in staat om notificaties te verwerken in het tempo waarin producers deze aanbieden. Het is daarom belangrijk dat consumers detecteren en aangeven wanneer dat het geval is en dat producers op deze signalen acteren door de snelheid te vertragen. Zie ook Richtlijnen afleverbetrouwbaarheid Notificaties.

Geef consumers de gelegenheid om met wijzigingen in notificaties om te gaanbewerken

Notificeren moet blijven functioneren als de inhoud van notificaties in de loop der tijd wijzigt. Bijv. door tijdelijke meerdere versies van notificaties te verstrekken of door gebruik te maken van versionering van notificaties.

Neem privacyaspecten vroegtijdig mee bij het ontwerpbewerken

Het is belangrijk om te voldoen aan privacywetgeving zoals de AVG. Dit vraagt in ieder geval dat vantevoren goed wordt nagedacht over grondslag en doelbinding van gegevens die worden uitgewisseld. Daarnaast is dataminimalisatie uitgangspunt. Zorg ervoor dat consumers niet meer gegevens ontvangen dan passend bij hun gebruik.

Abonneren op BSN met POST operatiebewerken

Gebruik een POST operatie als consumers zich abonneren op notificaties voor een specifiek BSN. Dit voorkomt dat deze als onderdeel van de request URL worden vastgelegd in logbestanden.

Voorkom waar mogelijk persoonsgegevens in notificatiesbewerken

Persoonsgegevens zijn gevoelig en compromittering ervan moet worden voorkomen. Voorkomen is beter dan genezen. Voor versleuteling en pseudonimisering zijn aanvullende maatregelen noodzakelijk, die niet triviaal zijn. Als notificaties naar meerdere consumers worden verstuurd door een intermediair kan standaard PKI versleuteling naar de consumer niet worden ingezet om persoonsgegevens inhoudelijk te versleutelen. Intermediairs kunnen namelijk standaard niet worden vertrouwd en het is dus onverstandig om persoonsgegevens onversleuteld bij een intermediair te verwerken.

Door gebruik te maken van informatiearme notificaties met daarin uitsluitend een betekenisloze identificatie van de gebeurtenis kunnen consumers vervolgens zelf op veilige wijze de bijbehorende gevoelige gegevens opvragen. Bij deze bevraging kunnen reguliere standaarden voor beveiliging worden gevolgd. Als er geen intermediair wordt gebruikt en de producer de consumers wel zelf kent, dan is het ook mogelijk om PKI toe te passen voor het versleutelen van gegevens per specifieke consumer.

Laat waar mogelijk filtering uitvoeren door consumersbewerken

Soms is het niet mogelijk of wenselijk om alle wensen met betrekking tot ontvangst van notificaties via op te geven filtercriteria te realiseren. Het voorkomt het realiseren van complexe filtervoorzieningen voor een beperkt aantal consumers, voor situaties waarin alleen de consumers kunnen beslissen. Dataminimalisatie blijft echter het streven.

Versleutel waar nodig de payload van notificatiesbewerken

Voor attributen binnen het payload-gedeelte van een bericht geldt dat ze zodanig versleuteld kunnen worden dat alleen consumers (en dus geen intermediaries) gegevens kunnen lezen. Het biedt extra garanties dat gegevens niet door onbevoegden worden ingezien. Dit is alleen relevant als er gevoelige gegevens worden uitgewisseld en transportversleuteling onvoldoende zekerheid biedt. Dit betekent wel dat eigenschappen waarop filtering nodig is onderdeel moeten zijn van de context in plaats van de payload.

Gebruik het Nederlands profiel op CloudEventsbewerken

Er is inmiddels een Nederlands profiel op de CloudEvents standaard ontwikkeld. NL GOV profile for CloudEvents is een set Nederlandse afspraken over het gebruik van de internationale standaard CloudEvents. Deze standaard wordt beheerd door Logius. Het gebruik van dit profiel verhoogt de standaardisatie en daarmee de interoperabiliteit van de uitwisseling van notificaties.

Het Nederlands profiel standaardiseert ondermeer de eigenschappen die onderdeel uit zouden moeten maken van een notificatie. Dit betreft eigenschappen zoals een unieke identificatie, de bron, de versie van het profiel en het gebeurtenistype. Er is ook een handreiking bij de standaard vanuit Logius beschikbaar. Het beschrijft op welke wijze gegevens in JSON zouden moeten worden opgenomen in notificaties. Het beschrijft ook een standaard werkwijze voor het gebruik van Web Hooks.

Gebruik gestructureerde notificatiesbewerken

De handreiking bij de NL GOV profile voor CloudEvents beschrijft dat er drie modes zijn om notificaties te versturen: gestructureerd, batched en binair. De gestructureerde vorm van uitwisseling heeft de voorkeur. Deze vorm is zelfbeschrijvend en zorgt ervoor dat de berichtinhoud protocolonafhankelijk is. Het faciliteert daardoor ook beter het uitvoeren van protocolvertalingen in de keten.

Publiceer gebeurtenistypes en aanbieders in een catalogusbewerken

Vindbaarheid van gebeurtenistypes en aanbieders van gebeurtenissen is essentieel om notificaties te kunnen ontvangen en gebruiken. Gebeurtenistypes zijn vergelijkbaar met API's en we vinden het ook belangrijk dat hebruikbare API's vindbaar zijn in catalogi.

Catalogi kunnen zowel binnen organisaties of domeinen bestaan, naast landelijke catalogi. Voor elk datastelsel zou er een catalogus beschikbaar moeten zijn.

Voorkom waar mogelijk afhankelijkheid van volgordelijkheid van notificatiesbewerken

Het is technisch ingewikkeld om te borgen dat notificaties die worden verzonden ook altijd exact in die volgorde worden verwerkt. Het omgaan met volgordelijkheid is ook primair een applicatieverantwoordelijkheid.

Bepaal dus situationeel of volgordelijkheid van berichten wel echt belangrijk is om af te dwingen. De consumer moet intelligent genoeg zijn om de verwerking goed te laten verlopen.

Borg dat notificaties minimaal één keer worden afgeleverdbewerken

Notificaties waarbij de producer geen enkele vorm van vertrouwen van ontvangst krijgt hebben weinig waarde. Er zijn allerlei niveaus van aflevergaranties. At-least-once is eenvoudig te implementeren en biedt een belangrijke vertrouwensbasis. Producers weten niet hoeveel waarde een notificatie heeft voor een consumer en hebben daarom een verantwoordelijkheid om hun uiterste best te doen om notificaties af te leveren. Exactly-once is ingewikkelder te implementeren en in veel gevallen niet nodig. At-most-once biedt onvoldoende garanties.

Borg bij het gebruik van communicatiekanalen die zelf geen aflevergaranties bieden dat de aflevering bij de consumer idempotent is. Idempotent betekent dat eenmalige verwerking dezelfde impact en betekenis heeft als meermalige verwerking. Door gebruik te maken van idempotentie kan het verzenden van de notificatie net zo lang worden geprobeerd totdat de consumer de aflevering heeft bevestigd. Het is daarbij de verantwoordelijkheid van de consumer om duplicaten te filteren. Gebruik van de richtlijn op developer.overheid.nl is aanbevolen.

Ontwikkel notificaties contract-firstbewerken

Het heeft een aantal belangrijke voordelen om eerst specificaties op te stellen en af te stemmen, alvorens te starten met de implementatie van notificaties. Het ontkoppelt de teams/partijen, doordat vooraf duidelijk is wat de afhankelijkheden zijn en wat de betekenis is van de gehanteerde begrippen. De kans op grotere wijzigingen wordt hierdoor ook veel kleiner. Het leidt tot betere documentatie en daarmee ook tot snellere onboarding en testbaarheid.

Dit betekent dat voorafgaand aan het implementeren van notificaties eerst de gebeurtenistypes formeel worden beschreven. Ook de gebruikte begrippen en het gehanteerde gegevensmodel zouden eerst moeten zijn uitgekristalliseerd.

Producers definiëren gebeurtenissenbewerken

Een gebeurtenis is iets dat gebeurt in het domein van de producer en staat daarmee in de basis los van het gebruik door een consumer. Consumers kunnen uiteraard wel bepaalde informatiebehoeften hebben, die invloed kunnen hebben op welke gegevens over gebeurtenissen worden vastgelegd en uitgewisseld. Het is echter uiteindelijk aan de producer om te bepalen of deze gegevens ook ingewonnen kunnen worden en tegen acceptabele kosten.

Producers leveren dan ook de specificatie van gebeurtenissen, na afstemming van consumers over hun informatiebehoeften. Gebeurtenissen hanteren daarbij de taal zoals gangbaar bij de producer. Deze dient dan ook duidelijk gedefinieerd te zijn in de vorm van begrippen en gegevensmodellen. Bij het notificeren kunnen er wel filters worden gedefinieerd die een voor een consumer relevante selectie maken van de gegevens over de gebeurtenis. Als een bepaalde groep consumers geïnteresseerd is in een bepaalde subset van notificaties, dan zou het ook mogelijk moeten zijn om daar een filter op te zetten.

Op deze pagina