CompanyBelgium API
Commencer
Documentation / Webhooks

Webhooks

Les webhooks vous poussent les changements au lieu de vous faire interroger l’API. Abonnez un webhook à une ou plusieurs entreprises : CompanyBelgium envoie (POST) un événement signé à votre URL dès qu’une fiche surveillée change. Vous les créez et les gérez via l’API Webhooks.

Fonctionnement#

Charge utile de l’événement#

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

Vérifier la signature#

Chaque livraison porte un en-tête X-CompanyBelgium-Signature de la forme sha256=<hex> — le HMAC-SHA256 du corps brut de la requête, signé avec votre secret de webhook. Recalculez-le sur le corps brut et comparez en temps constant avant de faire confiance à l’événement.

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();
}

Réessais &amp; journal de livraison#

Les livraisons en échec (non-2xx ou timeout) sont réessayées avec un backoff exponentiel. Les 100 dernières tentatives sont disponibles via l’endpoint du journal de livraison, et vous pouvez envoyer un événement de test à tout moment.

⚠️

Traitez le secret HMAC comme un mot de passe. En cas de fuite, faites-le tourner depuis l’API Webhooks — l’ancien secret cesse immédiatement d’être valide.

Créer un 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"]
  }'