Aller au contenu
API BCEAPI BCEAPI des données d'entreprises belges
Cas d'usageTarifsDocumentationBac à sableObtenir une clé
🇬🇧 English🇫🇷 Français🇳🇱 Nederlands🇩🇪 Deutsch🇪🇸 Español
Obtenir une clé
API BCE / Cas d'usage / Surveiller des entreprises par webhooks

🔔 Surveiller des entreprises par webhooks

Vérifier un tiers une fois ne suffit pas : un client change d'adresse, un fournisseur cesse son activité. Les webhooks vous préviennent au lieu de vous obliger à interroger l'API.

Le problème#

Un portefeuille de clients ou de fournisseurs vieillit. Les adresses changent, des dénominations évoluent, des entreprises cessent leur activité. La première idée est d'interroger l'API chaque nuit pour toutes les entreprises du portefeuille : c'est coûteux en quota, et la plupart des réponses ne changent rien.

Les webhooks inversent la logique : vous déclarez une fois les numéros à surveiller, et c'est l'API qui appelle votre serveur quand une fiche surveillée change dans le registre.

Les données de l'API qui répondent#

  • POST /webhook : crée un webhook (nom, URL de réception, numéros à surveiller). Le secret de signature HMAC n'est renvoyé qu'une fois, dans cette réponse.
  • POST /webhook/{id}/subscriptions et DELETE /webhook/{id}/subscriptions : ajoutent ou retirent des numéros d'entreprise ou d'établissement.
  • GET /webhook/{id}/subscriptions : la liste des numéros surveillés par un webhook.
  • POST /webhook/{id}/trigger : envoie une livraison de test pour vérifier votre récepteur et votre contrôle de signature.
  • GET /webhook/{id}/events : le journal des 100 dernières tentatives de livraison, avec statut, code de réponse et horodatage.
  • PATCH /webhook/{id}/hmac-secret : fait tourner le secret de signature ; l'ancien cesse immédiatement d'être valide.

Chaque événement indique son type (création, mise à jour ou désactivation de la fiche, ou livraison de test), le numéro concerné et le type d'entité, et il est signé avec le secret du webhook. La vérification de signature est décrite pas à pas dans le guide des webhooks.

Exemple de requête#

"tok-comment"># 1. Create the webhook with a first enterprise to watch
"tok-comment">#    (the hmacSecret is returned only once: store it)
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":"Portfolio watch","url":"https://example.be/hooks/bce","entityNumbers":["1033.022.383"]}'
"tok-comment">
# 2. Add more enterprise numbers later
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/subscriptions \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"entityNumbers":["<another enterprise number>"]}'
"tok-comment">
# 3. Send a test delivery, then read the delivery log
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/trigger \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"
curl https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/events \
  -H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"

Mise en œuvre conseillée#

  • Vérifiez la signature de chaque livraison avant d'en tenir compte, sur le corps brut de la requête.
  • Répondez vite par un code 2xx, puis traitez l'événement en arrière-plan : relisez la fiche avec GET /enterprise/{num} pour connaître son nouvel état.
  • Rendez le traitement idempotent : une même livraison peut arriver plus d'une fois.
  • Ajoutez les numéros au webhook au moment où un client ou un fournisseur entre dans votre portefeuille, et retirez-les quand la relation se termine.
  • Consultez le journal de livraison quand votre récepteur a été indisponible, et déclenchez une livraison de test après chaque déploiement.

Limites à connaître#

  • Les événements suivent les mises à jour publiées par la BCE : ils arrivent après l'enregistrement d'un changement dans le registre, pas au moment de la décision.
  • Un webhook signale qu'une fiche a changé ; pour connaître la nouvelle valeur d'un champ, relisez la fiche.
  • Les livraisons en échec sont réessayées, mais un récepteur durablement indisponible peut manquer des événements : le journal des 100 dernières tentatives sert à les retrouver.
  • Les webhooks surveillent des numéros précis. Ils ne signalent pas les nouvelles entreprises d'un secteur ou d'une région.

Questions fréquentes#

Quels changements déclenchent un webhook ?

La création, la mise à jour ou la désactivation de la fiche d'une entreprise ou d'un établissement surveillé, telles que publiées par la BCE, ainsi que les livraisons de test que vous déclenchez.

Comment sécuriser la réception ?

Chaque livraison est signée en HMAC avec le secret du webhook. Vérifiez la signature sur le corps brut avant de traiter l'événement, et faites tourner le secret en cas de fuite.

Peut-on surveiller des établissements ?

Oui. Les abonnements acceptent des numéros d'entreprise et d'établissement.

Passer à la pratique

Créez une clé dans le portail développeur, puis suivez la documentation de référence pour chaque endpoint cité.

Obtenir une clé APILire la documentation

Documentation de référence

  • Guide des webhooks
  • API Webhooks

Autres cas d'usage

  • Vérifier un client ou un fournisseur avant de travailler avec lui
  • Enrichir automatiquement un CRM à partir du numéro d'entreprise
  • Valider un numéro de TVA (VIES) à la saisie d’une facture
  • KYC/KYB à l'ouverture d'un compte d'entreprise

Sur cette page

Le problèmeLes données de l'API qui répondentExemple de requêteMise en œuvre conseilléeLimites à connaîtreQuestions fréquentesPasser à la pratique
API BCEAPI BCE

Un produit développeur d'Espero-Soft Informatiques, fondé sur l'open data officiel BCE/KBO.

Produit

Cas d'usagePourquoi API BCETarifsFAQ

Développeurs

DocumentationRéférence APIPlayground APIJournal des versionsObtenir une clé

Entreprise

Données, conformité et Peppol ↗Company Belgium ↗Espero-Soft ↗

Légal

Mentions légalesConditions générales d’utilisation et de ventePolitique de confidentialitéPolitique relative aux cookies
© 2026 Espero-Soft Informatiques SRL · Tous droits réservés.Conçu en Belgique 🇧🇪