CompanyBelgium API
Get started
Documentation / Webhooks

Webhooks

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#

Event payload#

{
  "eventId": "evt_001",
  "type": "enterprise.updated",
  "entityNumber": "0403.170.701",
  "occurredAt": "2026-06-05T09:00:00.000Z",
  "data": { "changed": ["address", "denomination"] }
}

Verify the signature#

Every delivery carries an X-CompanyBelgium-Signature header of the form sha256=<hex> — the HMAC-SHA256 of the raw request body, keyed with your webhook secret. Recompute it on the raw body and compare in constant time before trusting the event.

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 signature = (header || "").replace(/^sha256=/, "");
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)      // whsec_...
    .update(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 &amp; delivery log#

Failed deliveries (non-2xx or timeout) are retried with exponential backoff. The last 100 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_KEY" -H "X-API-Secret: $API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prod listener",
    "url": "https://example.be/hooks/bce",
    "entityNumbers": ["0403.170.701"]
  }'