Documentatie / Webhooks

API BCE webhooks: wijzigingen van ondernemingen volgen

Webhooks van API BCE: ontvang een HMAC-ondertekende gebeurtenis zodra een gevolgde onderneming wijzigt in de KBO. Aanmaken, inhoud, controle, pogingen.

Webhooks push changes to you instead of you polling. Subscribe a webhook to one or more enterprises and CompanyBelgium POSTs a signed event to your URL whenever a watched record changes. You create and manage them through the Webhooks API.

How it works#

  • Create a webhook with a target url and the entity numbers to watch.
  • Store the hmacSecret returned at creation: it is shown only once.
  • We POST a JSON event to your URL on every change; respond with 2xx quickly to acknowledge it.

Event payload#

{
  "event": "update",
  "entityNumber": "1033022383",
  "entityType": "enterprise",
  "data": "...",
  "timestamp": "..."
}

Verify the signature#

Every delivery carries an X-CompanyBelgium-Signature header of the form sha256=<hex>: the HMAC-SHA256 of <timestamp>.<raw body>, keyed with your webhook secret, where the timestamp is the X-CompanyBelgium-Timestamp header (Unix milliseconds). Recompute it and compare in constant time before trusting the event; rejecting timestamps older than 5 minutes protects against replays.

import crypto from "node:crypto";

// Express handler: needs the RAW request body
export function handleWebhook(req, res) {
  const header = req.header("X-CompanyBelgium-Signature"); // "sha256=<hex>"
  const timestamp = req.header("X-CompanyBelgium-Timestamp"); // Unix milliseconds
  const signature = (header || "").replace(/^sha256=/, "");
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${req.rawBody}`)
    .digest("hex");

  const ok = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.rawBody);
  // ... process event, then ack quickly
  res.status(200).end();
}

Retries & delivery log#

A delivery that gets a 5xx, a network error or no answer within 10 seconds is retried up to 3 times. The most recent attempts are available from the delivery-log endpoint, and you can send a test event at any time.

⚠️

Treat the HMAC secret like a password. If it leaks, rotate it from the Webhooks API: the old secret stops working immediately.

Create a webhook#

curl -X POST https://companybelgium.be/api/v2/webhook \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prod listener",
    "url": "https://example.be/hooks/bce",
    "entityNumbers": ["1033.022.383"]
  }'

Wanneer webhooks van API BCE het verschil maken#

Webhooks zijn nuttig zodra je een groep ondernemingen langere tijd volgt. Zonder webhooks moet je die lijst geregeld opnieuw ophalen. Dat kost verzoeken en levert meestal niets nieuws op. Met webhooks krijg je daarentegen alleen een bericht als er echt iets verandert.

Typische toepassingen zijn de volgende:

  • Kredietbeheer: een melding wanneer een klant met openstaande facturen wijzigt.
  • Leveranciersbeheer: je aankoopafdeling verwittigen bij een wijziging bij een strategische leverancier.
  • KYB-opvolging: een klantendossier opnieuw laten beoordelen na een wijziging in het register.
  • CRM-synchronisatie: adres of naam automatisch bijwerken in je CRM.

Webhooks zitten in de formule API Pro. Bovendien zijn ze nog niet beschikbaar in testmodus.

Een robuuste ontvanger bouwen#

Je ontvanger moet snel antwoorden. Een levering zonder antwoord binnen 10 seconden wordt immers opnieuw geprobeerd, tot 3 keer. Bevestig daarom eerst met een 2xx en verwerk het event daarna in een wachtrij. Zo blokkeert trage verwerking nooit de bevestiging.

Controleer vervolgens altijd de handtekening, voordat je het event vertrouwt. Gebruik daarvoor de ruwe body, niet een opnieuw geserialiseerde versie. Vergelijk in constante tijd en weiger timestamps ouder dan 5 minuten. Zo bescherm je je systeem tegen vervalste en herhaalde berichten.

Omdat een levering opnieuw kan komen, moet je verwerking idempotent zijn. Hetzelfde event twee keer verwerken mag dus geen dubbele actie geven. Haal bovendien na een event de actuele fiche op, als je volledige gegevens nodig hebt.

Opvolgen en testen#

Stuur na de configuratie een testlevering via het trigger-endpoint. Bekijk daarna het afleverlog met responscodes en foutmeldingen. Zie je herhaalde fouten, pauzeer dan de webhook met de vlag disabled terwijl je het probleem oplost. Alle endpoints staan in de webhooks-referentie.

Houd ten slotte je lijst met abonnementen klein en relevant. Volg alleen ondernemingen waarvoor een wijziging echt een actie vraagt. Zo blijft je ontvanger rustig en gaat elke melding van API BCE naar iemand die er iets mee doet. Vertrekt een klant, verwijder dan ook zijn nummer uit de abonnementen.

Veelgestelde vragen over API BCE en webhooks#

Wat als mijn server even onbereikbaar is?

Een levering die een 5xx, een netwerkfout of geen antwoord binnen 10 seconden krijgt, wordt tot 3 keer opnieuw geprobeerd. Daarna vind je de poging terug in het afleverlog.

Ik ben mijn HMAC-secret kwijt. Wat nu?

Het secret wordt maar één keer getoond. Vernieuw het daarom via het endpoint voor HMAC-rotatie. Het oude secret is dan meteen ongeldig.

Kan ik ook vestigingen volgen?

Ja. Je abonneert een webhook op ondernemings- of vestigingsnummers via het endpoint voor abonnementen.