Webhooks

Wijzigt er bij ons een vestiging, dan sturen wij een bericht naar jouw endpoint. Dat bericht bevat geen gegevens — alleen wat er gebeurd is en om welke vestiging het gaat. De gegevens zelf haal je daarna zelf op.

Die scheiding is met opzet: het ophaal-endpoint kan meegroeien met wat je nodig hebt, zonder dat het bericht zelf ooit verandert. Wat je één keer bouwt om die berichten aan te nemen, blijft werken.

Wat je krijgt#

Een POST naar het adres dat je met ons afsproken hebt:

POST https://systeem.klant.nl/webhooks/vakgarage
Content-Type: application/json
X-Event: establishment.updated
X-Delivery: c497c8fe-c1e2-4b8c-b003-ff466c1fa2ae
X-Timestamp: 1786000000
X-Signature: sha256=0fb8f2b526f515d245ec5e03548a7be42607fe9e2ff5d058a67422ea8ca1eded

{
    "event": "establishment.updated",
    "franchiseId": "220810",
    "crm_id": "01a0f3e2-7bf0-71c2-9896-805d5d965ea6"
}

De body gaat compact over de lijn; hierboven staat hij ingesprongen om hem leesbaar te houden.

De headers#

De events#

Je krijgt alleen de events waarop je bent aangemeld.

De twee sleutels#

franchiseId is het klantnummer, crm_id het onveranderlijke nummer van de organisatie. Een klantnummer kán in ons CRM wijzigen; crm_id niet. Wil je zeker weten dat je dezelfde vestiging voor je hebt, gebruik dan crm_id.

De ondertekening controleren#

Wij ondertekenen de tijdstempel en de body samen met het geheim dat je van ons kreeg:

X-Signature = "sha256=" + hmac_sha256("<X-Timestamp>.<ruwe body>", geheim)

Let op twee dingen:

1. De punt tussen de tijdstempel en de body hoort erbij.
2. De ruwe body, byte voor byte zoals hij binnenkomt. Haal hem niet door een JSON-decoder en weer terug — dan verandert de tekst en klopt de ondertekening niet meer.

In PHP:

$signed = $request->header('X-Timestamp') . '.' . $request->getContent();

$expected = 'sha256=' . hash_hmac('sha256', $signed, $secret);

// hash_equals en niet ===, zodat de vergelijking geen reactietijd prijsgeeft.
if (! hash_equals($expected, $request->header('X-Signature'))) {
    abort(401);
}

Weiger oude afleveringen#

Toets X-Timestamp ook op ouderdom — wij houden zelf vijf minuten aan. Zonder die toets kan iemand die een aflevering onderschept hem onbeperkt blijven herhalen; de ondertekening blijft immers geldig.

if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    abort(401);
}

Ontdubbelen#

Mislukt een aflevering, dan proberen wij het opnieuw met hetzelfde X-Delivery. Houd bij welke nummers je al verwerkt hebt en sla een herhaling over.

Meerdere wijzigingen aan dezelfde vestiging kort na elkaar vouwen wij samen tot één bericht. Dat kost je niets: je haalt toch de actuele stand op.

Antwoorden#

Antwoord met een 2xx zodra je het bericht hebt aangenomen, en doe het ophalen daarna. Een traag antwoord laat ons denken dat het misging.

Die laatste regel is bewust: een 403 of 422 betekent dat er iets aan de aflevering zelf niet deugt, en een volgende poging levert exact dezelfde fout op.

Opnieuw proberen#

Maximaal vijf pogingen, met oplopende wachttijd: 30 seconden, 2 minuten, 5 minuten, 15 minuten en 1 uur. Daarna geven wij het op en zie je dat in ons beheerscherm.

De gegevens ophalen#

Het bericht vertelt je alleen dát er iets gewijzigd is. De gegevens haal je op bij het endpoint dat wij met je afgesproken hebben, met franchiseId of crm_id uit de body.

Bij establishment.deleted bestaat die vestiging niet meer; dat endpoint geeft dan een 404. Dat is het signaal dat je hem aan jouw kant kunt opruimen.

Testen#

Bij elke webhook in de API-referentie (onder Webhooks, Testbericht sturen) stuur je jezelf een echte, ondertekende aflevering. Vul je gedeelde geheim in en wij versturen hem naar het adres dat bij jouw aanmelding hoort — zo controleer je of je endpoint hem aanneemt en of je ondertekening klopt, zonder op een echte wijziging te hoeven wachten.

Het geheim kwijt?#

Neem contact op met de beheerder. Die kan een nieuw geheim genereren; vanaf dat moment worden afleveringen met het oude geheim door jou terecht geweigerd, dus zet het nieuwe er meteen in.