Documentation / Webhooks

API BCE webhooks: track changes to Belgian companies

API BCE webhooks: receive an HMAC-signed event as soon as a watched company changes in the BCE. Creating a webhook, payload, signature check and retries.

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"]
  }'

When webhooks beat polling#

Polling a portfolio every day costs one request per company, even when nothing changed. With webhooks, you receive an event only when a watched record changes. As a result, you save quota and react faster. Webhooks are part of the Pro plan.

  • Credit monitoring: hear about a change on a customer you invoice on credit.
  • Periodic KYB review: refresh a compliance file only when the company record moves.
  • CRM sync: update names and addresses without a nightly full refresh.
  • Supplier master data: keep payment records aligned with the register.

A robust API BCE webhook receiver#

First, read the raw request body before any JSON parsing, because the signature covers <timestamp>.<raw body>. Then, compare signatures in constant time and reject timestamps older than 5 minutes. Next, answer with a 2xx status quickly and hand the work to a queue. A delivery without an answer within 10 seconds is retried up to 3 times. Therefore, slow handlers create duplicate deliveries.

For the same reason, make your processing idempotent. In other words, handling the same event twice must leave your data unchanged. Also, when you need the full record, fetch it again with the enterprise endpoint after the event.

Security deserves a second look. Accept deliveries only over HTTPS, and keep the secret in the same vault as your API credentials. Moreover, log rejected signatures with the source address, because a burst of rejections may point to a probe or a misconfigured proxy. In addition, test the receiver end to end with the trigger endpoint. It sends a manual event that you can then find in the delivery log.

Operating webhooks in production#

The delivery log shows the latest attempts with response codes and error messages. Check it when a customer says an update never arrived. In addition, send a test event after each deployment of your receiver. If the secret leaks, rotate it at once. However, the old secret stops working immediately, so update your receiver in the same step. Finally, note that webhooks are not available in test mode yet.

API BCE webhooks FAQ#

I lost my webhook secret. What now?

The secret is shown only once. So, rotate it through the Webhooks API and store the new value right away.

My endpoint was down for a while. Did I lose events?

Failed deliveries are retried up to 3 times. After that, read the delivery log and refetch the affected records with API BCE.

Which plan includes API BCE webhooks?

Webhooks are part of the API Pro plan, together with directors and annual accounts.