Wat zijn webhooks en hoe richt je deze in?

Wat zijn webhooks

Webhooks zijn automatische meldingen die MKG naar een extern systeem verstuurt zodra er een gebeurtenis plaatsvindt, zoals het aanmaken, wijzigen of verwijderen van gegevens. In plaats van regelmatig informatie op te vragen via een API, ontvang je met webhooks direct een bericht zodra er iets verandert.

Webhooks zijn vooral interessant wanneer je realtime integraties wilt bouwen. Denk aan het automatisch synchroniseren van relaties, orders, productiegegevens of facturen met een extern systeem. Hierdoor blijft je koppeling actueel zonder handmatige acties of periodieke polling.

Webhooks inrichten in MKG

Binnen MKG is een webhooks-module beschikbaar waarin je per endpoint en gebeurtenis bepaalt naar welke URL een melding wordt verstuurd. Je configureert hierbij het volgende:

• URL van jouw endpoint
• Secret key voor verificatie
• Eventtype, zoals create, update of delete
• Tabel waarop het event van toepassing is

Optioneel kun je ook de volgende configuraties doen:

• Veldfilters
• Condities

Beschikbaarheid

• Versie: webhooks zijn beschikbaar vanaf MKG 5 versie ***. Het exacte versienummer volgt bij de definitieve vrijgave. De functionaliteit is momenteel in bèta.
• Licentie: webhooks vallen binnen de MKG Exchange-licentie.
• Rechten: alleen MKG-gebruikers met beheerdersrechten kunnen webhooks inrichten.

Eerste gebruik

Voordat je webhooks voor het eerst gebruikt, richt je het volgende in:

1. Voer in de module 'MKG batch taken log' met de knop [Credentials] een MKG-gebruiker met het bijbehorende wachtwoord in.
2. Maak bij voorkeur een gebruiker 'Webhooks' aan en ken deze geen rechten of licentie toe. De gebruiker moet wel actief zijn.
3. Start de broker met de knop [Start broker].

URL

De webhook-URL is het adres waar MKG de berichten naartoe stuurt. Dit moet een extern bereikbare URL zijn die via HTTPS inkomende JSON-data kan verwerken. Bij elke gebeurtenis stuurt MKG automatisch een POST-verzoek naar deze URL.

MKG verstuurt webhooks niet vanaf vaste IP-adressen. Je kunt je firewall dus niet op basis van IP-adressen configureren. Controleer daarom altijd de handtekening van het bericht.

Secret key

MKG genereert voor elke webhook een secret key. Met deze sleutel valideert de ontvangende applicatie de digitale handtekening die bij elk event wordt meegestuurd. Door deze handtekening te controleren, weet je zeker dat het bericht daadwerkelijk door MKG is verzonden.

Deel de secret key niet met derden.

Wil je de secret key vernieuwen, bijvoorbeeld omdat deze is gedeeld of gelekt, klik dan in de webhook-module op [Maak een nieuwe sleutel aan]. De oude sleutel is direct ongeldig. Pas de secret key daarom meteen aan in de ontvangende applicatie, anders kan de handtekening van nieuwe berichten niet meer worden gevalideerd.

Events

Een event bepaalt wanneer de webhook moet worden geactiveerd en een bericht moet gaan versturen.

Je kunt webhooks instellen voor alle endpoints die in de module 'Data Dictionary' in MKG staan. De endpointnamen (zoals rela en vorr) zijn dezelfde als de endpoints in de MKG API.

Je kunt kiezen uit:

• create_[endpoint]: melding bij het aanmaken van een record
• update_[endpoint]: melding bij het wijzigen van een record
• delete_[endpoint]: melding bij het verwijderen van een record

Voer de events kommagescheiden in het eventsveld in. Het advies is om per endpoint een eigen webhook in te richten.

Hier is een voorbeeld voor het ontvangen van nieuwe, gewijzigde en verwijderde records op het relaties-endpoint (rela): create_rela,update_rela,delete_rela

Velden

In het veldenmenu selecteer je de velden waarvan een wijziging een update-event veroorzaakt. Hiermee voorkom je dat er onnodige meldingen worden verstuurd. Je kunt alleen databasevelden selecteren, geen berekende velden (LDM-velden). Velden gelden alleen voor update-events. Selecteer je geen velden, dan reageert de webhook op een wijziging in alle velden.

Condities

Met condities kun je bepalen dat een webhook alleen wordt geactiveerd wanneer aan een bepaalde voorwaarde wordt voldaan. De syntax is gelijk met die van LDM-velden. Een conditie geldt voor alle events van de webhook (create, update en delete). Condities kun je alleen op databasevelden zetten, niet op berekende velden (LDM-velden).

Webhooks gelden administratie-overstijgend. Wil je alleen events ontvangen van een bepaalde administratie, neem dan bijvoorbeeld [admi_num]=1 op in de conditie.

Hier is een voorbeeld voor het exclusief ontvangen van wijzigingen voor relatienummer 12: [rela_num]=12

Events tabblad

Op het tabblad 'Events' zie je alle verzonden en nog te verzenden webhook-events. Hier kun je handmatig webhook-events opnieuw versturen, verwijderen en logdetails bekijken. Webhook-events worden door MKG automatisch binnen enkele minuten verstuurd. Als de URL niet bereikbaar is, blijft het webhook-event in de status 'Gereed om te versturen' staan. MKG probeert later op verschillende intervallen om het webhook-event opnieuw te versturen. Gaat een levering mis, dan vind je de logdetails op dit tabblad.

Testen

Met de knop [Stuur een test bericht] in de webhook-module verstuur je een testbericht naar je endpoint. Zo controleer je of je URL bereikbaar is en of je de handtekening correct valideert. Het testbericht heeft de volgende payload:

{
    "document": 0,
    "documentname": "test",
    "createdon": null,
    "rowkey": "test"
}

Webhooks ontvangen

Om webhook-events te ontvangen moet jouw applicatie luisteren naar de URL die in MKG is ingesteld. Deze URL ontvangt een POST-verzoek met JSON-data. De structuur van de melding is uniform en gebaseerd op de Standard Webhooks-specificatie.

Voorbeeld

Een voorbeeld van de body (payload) van een webhook-event dat MKG verstuurt:

{
    "type": "update_rela",
    "timestamp": "2026-03-04T10:58:54.000",
    "data": {
        "document": 4,
        "documentname": "rela",
        "createdon": "2025-12-23T11:45:35.000",
        "rowkey": "0x0000000000f0088d"
    }
}

Opbouw:

• type: het type actie, zoals create, update of delete
• timestamp: het tijdstip waarop de wijziging plaatsvond, in UTC
• data:
  • document: het nummer van het endpoint
  • documentname: de naam van het endpoint
  • createdon: de datum en tijd waarop de gewijzigde record oorspronkelijk is aangemaakt
  • rowkey: de identificatie van de gewijzigde record

De velden timestamp en createdon hebben altijd hetzelfde formaat (jjjj-mm-ddThh:mm:ss.fff). Bij een delete-event bevat de payload dezelfde velden.

Headers

Bij elk webhook-event stuurt MKG de volgende headers mee:

Controleer de handtekening in webhook-signature met de secret key, zoals beschreven in de Standard Webhooks-specificatie. Verwerk het bericht pas als de handtekening klopt.

Zo valideer je de handtekening:

1. Zet de te ondertekenen tekst samen: webhook-id, een punt, webhook-timestamp, een punt en de ongewijzigde body (webhook-id.webhook-timestamp.body).
2. Decodeer de secret key met Base64 en bereken van de tekst uit stap 1 de HMAC met SHA-256, met de gedecodeerde key als sleutel.
3. Codeer het resultaat als Base64 en vergelijk dit met de waarde achter v1, in webhook-signature.

De secret key is Base64-gecodeerd, zonder whsec_-prefix. Decodeer de key dus eerst met Base64 en gebruik de gedecodeerde bytes als sleutel voor de HMAC. De Standard Webhooks-bibliotheken doen dit automatisch.

Antwoord van je endpoint

In veel gevallen hoef je de response niet zelf in te richten, omdat deze automatisch wordt verzorgd, bijvoorbeeld door de tool of het platform waarmee je de webhook ontvangt. Ontvang je webhooks met een eigen applicatie, zorg dan dat je endpoint reageert met een 2xx-statuscode (bijvoorbeeld 200 OK) zodra je het bericht hebt ontvangen. MKG beschouwt het event dan als succesvol verzonden. Bij een andere statuscode of een onbereikbare URL blijft het event in de status 'Gereed om te versturen' staan en probeert MKG het later opnieuw.

Rowkey

Uit veiligheidsoverwegingen wordt alleen de rowkey van de gewijzigde record via de webhook verstuurd. Met behulp van deze rowkey kan via de MKG API de bijbehorende record worden opgehaald. De rowkey kan vervolgens als primary key worden gebruikt. Rowkeys zijn binnen het endpoint uniek, maar een rowkey van een verwijderde record wordt vaak direct opnieuw gebruikt voor een nieuwe record. Daarom stuurt MKG ook createdon mee in de payload. De combinatie van rowkey en createdon is uniek en kun je gebruiken als primary key.

Bij een delete-event bestaat de record niet meer in MKG en kun je deze dus niet meer via de API ophalen. Gebruik de rowkey in dat geval om de bijbehorende record in je eigen systeem te identificeren en te verwijderen.