Hoe je externe systemen automatisch op de hoogte houdt van wijzigingen (webhooks) en externe systemen toegang geeft tot jouw gegevens via een API key.

De koppelingen vind je via Instellingen in het linker menu, tabblad Koppelingen. Dit tabblad is alleen toegankelijk voor administrators.

Er zijn twee soorten koppelingen:

• Webhooks (push) — het platform stuurt automatisch een bericht naar een extern systeem zodra er iets wijzigt
• API-toegang (pull) — een extern systeem haalt zelf gegevens op met een API key

Webhooks

Met een webhook ontvangt een extern systeem (bijvoorbeeld jouw ledenadministratie) automatisch een HTTP POST-bericht wanneer er iets verandert. De beschikbare events zijn:

• Nieuw lid en Lid gewijzigd
• Nieuwe activiteit en Activiteit gewijzigd

Een webhook toevoegen

1. Ga naar Instellingen → Koppelingen.
2. Klik op Webhook toevoegen.
3. Vul een herkenbare naam in (bijv. "koppeling ledenadministratie").
4. Vul de URL in van het ontvangende systeem. Dit moet een https-adres zijn dat POST-verzoeken accepteert.
5. Er wordt automatisch een secret gegenereerd. Dit wordt bij elk verzoek meegestuurd als X-Webhook-Secret-header, zodat het ontvangende systeem kan controleren dat het bericht echt van het platform komt. Kopieer het secret en bewaar het veilig.
6. Selecteer de events waarvoor je berichten wilt ontvangen (minimaal één).
7. Klik op opslaan.

In het formulier zie je een voorbeeld van de payload: de JSON die naar jouw URL wordt gestuurd. Het data-veld bevat altijd de actuele, volledige gegevens op het moment van versturen.

Een webhook testen

Klik bij een webhook op Test versturen. Er wordt direct een testbericht (webhook.test) naar de URL gestuurd en je ziet meteen of dat is gelukt, inclusief de HTTP-status.

Het afleverlog

Op het tabblad Afleverlog zie je per webhook alle verstuurde berichten, met tijdstip, event, HTTP-status en het aantal pogingen. De mogelijke statussen:

Mislukt een aflevering, dan wordt het bericht automatisch opnieuw geprobeerd met een oplopende wachttijd (maximaal 5 pogingen). Elke webhook toont bovendien een gezondheidsindicator (Gezond / Faalt) zodat je in één oogopslag ziet of de koppeling werkt.

Een webhook aanpassen of verwijderen

Je kunt een webhook bewerken (naam, URL, secret, events), tijdelijk deactiveren met de aan/uit-schakelaar, of verwijderen. Bij verwijderen wordt ook het afleverlog van die webhook verwijderd.

API-toegang (API keys)

Met een API key kan een extern systeem zelf gegevens ophalen uit jouw organisatie en activiteiten aanmaken — bijvoorbeeld een planningssysteem dat activiteiten inleest of aanmaakt.

Een API key aanmaken

1. Ga naar Instellingen → Koppelingen en scroll naar API-toegang.
2. Klik op API key aanmaken.
3. Vul een herkenbare naam in (bijv. "koppeling planningssysteem").
4. De sleutel wordt gegenereerd. Gebruik Sleutel tonen en Sleutel kopiëren om hem over te nemen in het externe systeem.

Het externe systeem stuurt de sleutel bij elke aanroep mee als X-Api-Key-header. Via de link Bekijk de API-documentatie (Swagger) vind je de technische documentatie van de beschikbare endpoints: locaties ophalen, activiteiten ophalen en activiteiten aanmaken.

In het overzicht zie je per sleutel wanneer deze is aangemaakt en wanneer hij voor het laatst is gebruikt — handig om te controleren of een koppeling daadwerkelijk actief is.

Een API key intrekken

Klik bij de sleutel op Intrekken en bevestig. Systemen die deze sleutel gebruiken verliezen direct de toegang. Ingetrokken sleutels kun je niet heractiveren — maak zo nodig een nieuwe aan.

Veiligheid: behandel het webhook-secret en de API key als een wachtwoord. Deel ze alleen met het systeem dat ze nodig heeft en trek een sleutel direct in als je vermoedt dat hij is uitgelekt.

Veelgestelde vragen

Wat is het verschil tussen een webhook en een API key? Een webhook is push: het platform stuurt zelf een bericht naar jouw systeem zodra er iets wijzigt. Een API key is pull: jouw systeem haalt op eigen initiatief gegevens op. Vaak gebruik je ze samen — de webhook meldt dat er iets is gewijzigd, waarna het systeem via de API details ophaalt.

Mijn webhook staat op "Faalt". Wat nu? Open het afleverlog en bekijk de laatste afleveringen: daar zie je de HTTP-status en de foutmelding. Controleer of de URL bereikbaar is en POST-verzoeken accepteert, en gebruik Test versturen om het direct te controleren.

Hoe controleert mijn systeem dat een webhook-bericht echt van het platform komt? Elk bericht bevat de X-Webhook-Secret-header met het secret van de webhook. Laat jouw systeem die waarde vergelijken met het secret dat je bij het instellen hebt gekopieerd.

Kan ik meerdere webhooks of API keys aanmaken? Ja. Je kunt bijvoorbeeld per extern systeem een eigen webhook en een eigen API key aanmaken, elk met een eigen naam. Zo kun je een koppeling gericht intrekken zonder de andere te raken.

Welke gegevens kan een extern systeem via de API benaderen? De externe API is beperkt: locaties en activiteiten ophalen, en activiteiten aanmaken. De volledige, actuele lijst staat in de API-documentatie (Swagger) waarnaar het portaal linkt.