Notificeren met Open Notificaties

De Notificaties API-specificatie stelt alle registraties in staat om te notificeren en alle applicaties om deze notificaties te ontvangen en op te acteren. En met "alle" bedoel ik hier ook echt alle. Zowel oud als nieuw, bestaande API's en nog te ontwikkelen API's. Dat maakt deze API enorm krachtig!

Zo koppelen ook de Objecten API maar straks ook de nieuwe Klantinteractie API's met de Notificaties API om notificaties te versturen.

Open Notificaties implementeert de Notificaties API-specificatie, en gebruik ik in de voorbeelden.

Voor gemeente Den Haag moest ik recent een korte technische uitleg maken over hoe de hele keten van notificaties werkt. Aan de hand van 4 stappen leg ik uit hoe je met notificaties aan de slag kan:

1. Abonneren op relevante notificaties
2. Een Zaak aanmaken
3. De informatie-arme "Zaak-aanmaak" notificatie ontvangen
4. De Zaak-gegevens ophalen

Voorbereiding

Wat heb je nodig? Nou, het volgende:

• Open Zaak instantie (installatie handleiding)
• Open Notificaties instantie (installatie handleiding)
• Open Zaak die gekoppeld is aan Open Notificaties (uitleg)
• Een Zaaktype in de Catalogus van Open Zaak (voorbeeld)
• API-credentials die toegang geeft tot zaken aanmaken in en ophalen uit Open Zaak (uitleg)

Snel aan de slag met een testomgeving waar dit allemaal al in is geregeld? Neem contact met ons op.

De keten in actie

Om te laten zien hoe notificaties werken, doe ik geen realistische use-case en puur het minimale wat nodig is om het technisch in actie te zien.

Eerst even dit

De Notificaties API-specificatie is zo generiek dat het lastig kan zijn alle informatie bij elkaar te schrapen. Hier enkele tips:

1. De beschikbare kanalen waar je een abonnement op kan nemen kan je opvragen via de Notificaties API. Dit is typisch de lijst van componenten die zich bekend hebben gemaakt bij Open Notificaties: zaken, documenten, besluiten, etc.
2. De kanaal-namen zijn vastgesteld in de API-specificaties van bijvoorbeeld de Zaken API hier: https://github.com/VNG-Realisatie/zaken-api/blob/master/src/notificaties.md
3. Op de URL hierboven, en dus per API, staan ook de beschikbare filters/kenmerken uitgelegd. De mogelijke waardes van deze filters/kenmerken staan dan weer genoemd in de API-specificaties zelf.

Let's go.

Wat er onder de motorkap gebeurt: Open Zaak stuurt een notificatie naar Open Notificaties, en Open Notificaties stuurt het bericht door naar alle abonnees.

1. Abonneren op relevante notificaties

We maken eerst een abonnement aan in Open Notificaties

POST https://open-notificaties.<YOURDOMAIN>/api/v1/abonnement
Authorization: Bearer <TOKEN>

{
"callbackUrl": "<YOUR URL>",
"auth": "Token Foobar",
"kanalen": [
{
"filters": {
"vertrouwelijkheidaanduiding": "openbaar"
},
"naam": "zaken"
}
]
}

Hier wordt een abonnement aangemaakt waarbij we aangeven een notificatie te willen ontvangen als er iets met een zaak wordt gedaan die "openbaar" is. We willen de notificatie graag ontvangen op de callback URL, hier ingevuld met <YOUR URL>.

Je kan bij <YOUR URL> bijvoorbeeld ook gebruik maken van https://webhook.site/ waar willekeurige data naartoe gestuurd kan worden. Ik gebruik deze vaak als ik nog geen software heb die om kan gaan met bepaalde berichten. Overigens zorgt het aanmaken van een abonnement, direct voor een POST-call op de callback URL.

Als je meteen het protocol wilt implementeren om notificaties te ontvangen, lees dan de specificatie. Python-guru? Bekijk dan onze open source library hiervoor.

2. Een Zaak aanmaken

Zaken zijn uitgebreide dossiers met documenten, besluiten, statussen en betrokkenen. Voor deze case doen we echter het minimum aan effort :)

POST https://open-zaak.<YOURDOMAIN>/zaken/api/v1/zaken
Authorization: Bearer <TOKEN>
Accept-Crs: EPSG:4326
Content-Crs: EPSG:4326

{
    "bronorganisatie": "286130270",
    "zaaktype":
"https://open-zaak.<YOURDOMAIN>/catalogi/api/v1/zaaktypen/cf57c196-982d-4e2b-a567-d47794642bd7",
    "verantwoordelijkeOrganisatie": "286130270",
    "vertrouwelijkheidaanduiding": "openbaar",
    "startdatum": "2023-08-10"
}

We maken enkel een Zaak aan, die "openbaar" is om door het abonnementsfilter te komen. We doen dit puur om een notificatie te triggeren van Open Zaak naar Open Notificaties, die alle abonnees notificeert (en laten we nou net een abonnement hebben aangemaakt in stap 1)

3. De informatie-arme "Zaak-aanmaak" notificatie ontvangen

Als het goed is krijgen we bijna direct een notificatie van Open Notificaties. Dat ziet er ongeveer zo uit:

Authorization: Token Foobar
Content-Type: application/json

{
  "kanaal": "zaken",
  "hoofdObject": "https://open-zaak.<YOURDOMAIN>/zaken/api/v1/zaken/eff4e073-52e7-43cd-b374-07673ddc6000",
  "resource": "zaak",
  "resourceUrl": "https://open-zaak.<YOURDOMAIN>/zaken/api/v1/zaken/eff4e073-52e7-43cd-b374-07673ddc6000",
  "actie": "create",
  "aanmaakdatum": "2023-08-10T14:15:25.014850Z",
  "kenmerken": {
    "bronorganisatie": "286130270",
    "zaaktype": "https://open-zaak.<YOURDOMAIN>/catalogi/api/v1/zaaktypen/cf57c196-982d-4e2b-a567-d47794642bd7",
    "vertrouwelijkheidaanduiding": "openbaar"
  }
}

We zien dat de "Authorization" header gevuld is met de waarde "auth" uit onze abonnement-call in stap 1. Verder zien we de o.a. het zaaktype (kenmerk.zaaktype URL), dat er een zaak is aangemaakt (actie: create), welke zaak is aangemaakt (hoofdObject URL), etc.

4. De Zaak-gegevens ophalen

De notificatie is uiteraard niet informatie-loos maar informatie-arm. Met de weinige informatie die we krijgen kunnen we nu de zaak opvragen die zojuist is aangemaakt.

We bevragen simpelweg de URL uit het "hoofdObject":

GET https://openzaak.<YOURDOMAIN>/zaken/api/v1/zaken/eff4e073-52e7-43cd-b374-07673ddc6000

Accept-Crs: EPSG:4326

Aangenomen dat we daar rechten toe hebben, zien we nu alle informatie van deze zaak.

Meer weten over Open Zaak of de ZGW API's? Lees ook eens hoe je koppelt met Open Zaak.

Wanneer krijgt de klant nou een notificatie?

Ja, goede vraag, maar dat is buiten scope van dit verhaal. Een applicatie die een notificatie ontvangt van Open Notificaties moet zelf beslissen wat het daar mee doet. Dit kan enorm verschillen: De applicatie kan de notificatie simpelweg negeren, een e-mail versturen aan de behandelaar, of juist de initiator, of een push bericht, of een cache-update doen...

Hoe de klant een notificatie ontvangt, hangt ook af van de persoonlijke voorkeuren. Die kunnen weer vastgelegd worden in het klantprofiel zoals dat bijvoorbeeld is gedaan in Open Klant.

Maar het korte antwoord is dus dat dat deel bij de specifieke applicatie ligt en hier de systeem-naar-systeem notificaties zijn uitgelegd.

Over de auteur

Joeri Bekker is een software ontwikkelaar in hart en nieren maar de laatste jaren vooral bezig met Common Ground projecten bij Maykin, in de rol van overkoepelend productowner. Al weer een paar jaar geleden heeft Joeri meegeholpen om RESTful API's bij VNG Realisatie te introduceren wat samenviel met de opkomst van Common Ground. In dat verlengde is Joeri aangehaakt bij het team dat de ZGW API's heeft ontwikkeld waarvoor hij ook heeft meegeholpen om de referentie implementatie ("werkende software") te realiseren op basis van de API specificaties.