Integratiehandleiding
Ontvang real-time wijzigingen voor de ondernemingen en vestigingen die u volgt.
Volledige flow
- Maak een webhook aan met uw HTTPS-URL en de entiteiten die u wilt volgen.
- Bewaar het HMAC-geheim zorgvuldig — het wordt slechts één keer geretourneerd.
- Bij de volgende KBO-sync triggert elke wijziging een ondertekende POST.
- Verifieer de handtekening aan de ontvangstkant voordat u de payload verwerkt.
Een webhook aanmaken
bash
curl -X POST https://companybelgium.be/api/v2/webhook \
-H "X-API-Key: $API_KEY" \
-H "X-API-Secret: $API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"name": "Production listener",
"url": "https://hooks.example.com/companybelgium",
"entityNumbers": ["1033022383", "0202239951"]
}'⚠️ Het veld `hmacSecret` wordt slechts één keer geretourneerd bij het aanmaken. Sla het nu op — u kunt het niet meer ophalen (alleen roteren via PATCH /hmac-secret).
Payload-formaat
http
POST https://hooks.example.com/companybelgium HTTP/1.1
Content-Type: application/json
X-CompanyBelgium-Signature: sha256=8e6c…
X-CompanyBelgium-Timestamp: 1747843200000
X-CompanyBelgium-Event: update
X-CompanyBelgium-Delivery: 9c1b…
{
"event": "update",
"entityNumber": "1033022383",
"entityType": "enterprise",
"data": {},
"timestamp": "2026-04-15T10:00:00.000Z"
}Verificatie van de handtekening
Reconstrueer de HMAC aan de ontvangstkant met uw geheim + tijdstempel en vergelijk in constante tijd.
javascript
import crypto from "node:crypto"
function verify(req, secret) {
const signature = req.headers["x-companybelgium-signature"]
const timestamp = req.headers["x-companybelgium-timestamp"]
const body = req.rawBody // Express: use express.raw() or capture before json()
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${body}`)
.digest("hex")
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
throw new Error("Invalid signature")
}
// Reject signatures older than 5 minutes (replay protection)
if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60_000) {
throw new Error("Timestamp too old")
}
}Retry-beleid
De dispatcher probeert tot 3 keer opnieuw bij netwerkfouten of 5xx, met exponentiële back-off (0,5s → 2s → 8s). 4xx wordt niet opnieuw geprobeerd. Alle pogingen zijn zichtbaar in GET /webhook/{id}/events.
Een test triggeren
Om uw integratie te testen zonder op een echte KBO-wijziging te wachten, gebruikt u het `trigger`-endpoint.
bash
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/trigger \
-H "X-API-Key: $API_KEY" \
-H "X-API-Secret: $API_SECRET" \
-H "Content-Type: application/json" \
-d '{"entityNumber":"1033022383","data":{"note":"manual test"}}'