Overzicht & scope

EKN (Eduarte Koppeling Notifications) is de notificatiekoppeling van Connect. Eduarte stuurt een melding zodra een resource wijzigt, zodat een afnemer weet dat er iets is veranderd en de nieuwe stand kan ophalen. De meldingen volgen de CloudEvents v1.0-standaard (zie https://cloudevents.io).

In tegenstelling tot de andere Connect-koppelingen roept de afnemer EKN niet aan. EKN is een ontvangstcontract (webhook): Eduarte doet een POST naar een callback-URL (aflever-URL) van de afnemer. Deze specificatie beschrijft daarom wat de afnemer moet implementeren en verwachten.

Status: in ontwikkeling. EKN is nog niet beschikbaar. Deze specificatie beschrijft de beoogde werking; details kunnen nog wijzigen.

• Versie: 1.0
• Standaard: CloudEvents v1.0
• Content-type: application/cloudevents+json
• Volledige OpenAPI-specificatie: meegeleverd als EKN_v1.0.yml.
• Interactieve referentie online: API-referentie van EKN

Werking

Wanneer in Eduarte een resource wordt aangemaakt, gewijzigd of verwijderd, stuurt EKN een lichtgewicht event. Dat event bevat géén volledige gegevens, maar een verwijzing naar de gewijzigde resource. De afnemer haalt vervolgens zelf de nieuwe stand op via de betreffende Connect-API.

Reikwijdte: één kanaal voor alle EKx-koppelingen

EKN is één gedeeld notificatiekanaal voor alle EKx-koppelingen. Of je voor een bepaalde koppeling events ontvangt, hangt ervan af of die koppeling voor jou als partner is aangezet in Eduarte: staat een koppeling uit, dan stuurt EKN daarvoor geen events.

Alle events — ongeacht de koppeling — worden afgeleverd op dezelfde, ene aflever-URL van de afnemer. Eén endpoint ontvangt dus de notificaties van alle voor de partner geactiveerde koppelingen; aan het type van het event herken je om welke koppeling en entiteit het gaat.

Op dit moment zijn event-types gedefinieerd voor EKP, EKS en EKOC (zie Event-types); uitbreiding naar andere EKx-koppelingen volgt naarmate EKN verder ontwikkeld wordt.

Aan de slag (aansluiten als ontvanger)

1. Implementeer een endpoint dat POST-verzoeken accepteert met content-type application/cloudevents+json en met 204 No Content antwoordt bij succesvolle ontvangst.
2. Meld je aflever-URL aan bij Eduarte (connect@eduarte.nl). Eén URL ontvangt de events van alle voor jou geactiveerde koppelingen.
3. Ontvang het pre-shared token dat Eduarte out-of-band met je deelt; valideer dit token op elk binnenkomend verzoek (zie Beveiliging).
4. Verwerk het event en haal de nieuwe stand op via de betreffende API (zie Nieuwe stand ophalen).

Het notificatie-endpoint

Foutsituaties die de afnemer kan teruggeven:

Structuur van een CloudEvent

Event-types

Het type volgt het patroon nl.topicus.eduarte.<entiteit>.<actie>, met als actie created, updated of deleted. De gedefinieerde entiteiten per koppeling:

Nieuwe stand ophalen

Een event is een signaal, geen gegevensoverdracht. Na ontvangst:

• Gebruik dataref om de gewijzigde resource direct op te halen via de betreffende Connect-API (het is het pad ten opzichte van de basis-URL van die API).
• Bij een deleted-event ontbreekt dataref; verwijder de resource dan aan jouw kant op basis van subject.
• Als alternatief (of als inhaalslag na downtime) kun je wijzigingen ophalen met de changed-since-parameter van EKP/EKB (waar beschikbaar).

Beveiliging

EKN gebruikt een vooraf gedeeld (pre-shared) bearer-token: Eduarte stuurt bij elk verzoek een vast token mee in de Authorization: Bearer <token>-header, dat out-of-band met de afnemer is gedeeld.

• Valideer dit token op elk binnenkomend verzoek en wijs verzoeken zonder geldig token af.
• Bied de aflever-URL alleen aan via HTTPS (TLS 1.2 of hoger).
• Behandel het token als geheim; roteer het in overleg met Eduarte.

Do’s & don’ts (voor ontvangers)

Do’s

• Antwoord snel met 204 en verwerk het event asynchroon; voorkom lange verwerkingstijden in de request.
• Wees idempotent: hetzelfde event (id) kan meer dan eens binnenkomen.
• Haal de nieuwe stand op via dataref/de API; vertrouw niet op gegevens in het event zelf.
• Houd rekening met volgorde: events komen niet noodzakelijk in volgorde binnen — gebruik time en de actuele API-stand als waarheid.

Don’ts

• Verwerk geen events zonder geldig token.
• Ga er niet van uit dat het event de volledige data bevat — dat doet het niet.
• Laat de verbinding niet lang openstaan; dat kan tot herhaalde aflevering leiden.

Beschikbaarheid & support

EKN wordt aangeboden als beheerde dienst; afspraken over beschikbaarheid en levering worden vastgelegd in de partnerovereenkomst. Vragen en meldingen kunnen bij Eduarte (connect@eduarte.nl).

Let op: concrete leveringsgaranties (retries, bewaartermijn, volgorde) worden vastgelegd zodra EKN beschikbaar komt en zijn nog te bevestigen.

Versiebeheer & status

EKN volgt de Connect-versioneringsstrategie (SemVer, major-versie in het pad). De huidige versie is 1.0 en in ontwikkeling.