Documentation / Webhooks

API BCE : webhooks pour suivre les changements d’entreprises

Webhooks API BCE : recevez un événement signé HMAC dès qu’une entreprise suivie change dans la BCE. Création, contenu, vérification et nouvelles tentatives.

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#

  • Créez un webhook avec une url cible et les numéros d’entité à surveiller.
  • Conservez le hmacSecret renvoyé à la création : il n’est affiché qu’une seule fois.
  • Nous envoyons (POST) un événement JSON à votre URL à chaque changement ; répondez vite en 2xx pour l’accuser.

Charge utile de l’événement#

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

Vérifier la signature#

Chaque livraison porte un en-tête X-CompanyBelgium-Signature de la forme sha256=<hex> : le HMAC-SHA256 de <timestamp>.<corps brut>, signé avec votre secret de webhook, le timestamp étant l’en-tête X-CompanyBelgium-Timestamp (millisecondes Unix). Recalculez-le et comparez en temps constant avant de faire confiance à l’événement ; refuser un timestamp de plus de 5 minutes protège contre le rejeu.

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

Réessais & journal de livraison#

Une livraison qui reçoit une erreur 5xx, une erreur réseau ou aucune réponse en 10 secondes est réessayée jusqu’à 3 fois. Les 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_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"]
  }'

Cas d’usage des webhooks API BCE#

Les webhooks conviennent dès que vous suivez un ensemble connu d’entreprises dans la durée. Plutôt que de relire chaque fiche chaque nuit, vous êtes prévenu quand une fiche surveillée change. Ils font partie de la formule API Pro.

  • Gestion des risques fournisseurs : recevez un événement quand un fournisseur stratégique change de statut.
  • Portefeuille clients : tenez votre CRM à jour sans rafraîchissement massif.
  • Comptabilité : repérez un changement d’adresse avant d’envoyer la prochaine facture.
  • Conformité : déclenchez une revue KYB quand la fiche d’un client évolue.

Concevoir un récepteur robuste#

D’abord, répondez vite. Une livraison sans réponse en 10 secondes est considérée comme un échec et sera réessayée. Votre récepteur doit donc vérifier la signature, enregistrer l’événement dans une file, puis répondre en 2xx. Le traitement métier se fait ensuite, en arrière-plan.

Ensuite, rendez le traitement idempotent. En effet, une livraison peut être réessayée jusqu’à 3 fois, et vous pourriez recevoir deux fois le même événement. Par exemple, relisez la fiche avec /enterprise/{num} plutôt que d’appliquer aveuglément une modification. Ainsi, rejouer un événement ne crée aucun doublon.

Enfin, calculez la signature sur le corps brut, avant tout parsing JSON. Beaucoup de frameworks reformatent le corps, ce qui invalide le HMAC.

Exploiter et surveiller#

Envoyez une livraison de test après chaque déploiement de votre récepteur. Consultez aussi régulièrement le journal de livraison : codes de réponse, nombre d’essais et messages d’erreur y figurent. De plus, prévoyez une rotation du secret HMAC dans vos procédures. L’ancien secret cesse immédiatement d’être valide, donc mettez à jour votre configuration juste après.

Mettre en production vos webhooks API BCE#

Avant d’abonner votre portefeuille complet, commencez petit. D’abord, créez un webhook vers un environnement de préproduction et abonnez-y quelques entreprises. Ensuite, envoyez une livraison de test et vérifiez le traitement de bout en bout. Une fois le récepteur validé, créez le webhook de production avec une URL dédiée. Enfin, ajoutez les abonnements par petits lots depuis votre CRM. De plus, surveillez le récepteur comme un service critique : une indisponibilité prolongée vous ferait manquer des changements.

Questions fréquentes sur les webhooks API BCE#

Puis-je tester les webhooks en mode test ?

Pas encore. Les webhooks ne sont pas disponibles en mode test. Utilisez plutôt l’endpoint de livraison de test sur un webhook réel.

Que faire si mon serveur était en panne ?

Les livraisons échouées sont réessayées jusqu’à 3 fois. Au-delà, consultez le journal de livraison puis relisez les fiches concernées pour vous resynchroniser.

Comment éviter les attaques par rejeu ?

Vérifiez l’en-tête X-CompanyBelgium-Timestamp et refusez un événement de plus de 5 minutes. Comparez ensuite la signature en temps constant.