Skip to content
API BCEAPI BCEBelgian company data API
Use casesPricingDocumentationSandboxGet API key
🇬🇧 English🇫🇷 Français🇳🇱 Nederlands🇩🇪 Deutsch🇪🇸 Español
Get API key
API BCE / Use cases / Monitor companies with webhooks

🔔 Monitor companies with webhooks

Checking a third party once is not enough: a client moves, a supplier stops trading. Webhooks notify you instead of making you poll the API.

The problem#

A portfolio of clients or suppliers ages. Addresses change, names evolve, companies stop trading. The first idea is to query the API every night for every company in the portfolio: it costs quota, and most responses change nothing.

Webhooks reverse the logic: you declare once the numbers to watch, and the API calls your server when a watched record changes in the register.

The API data that answers it#

  • POST /webhook: creates a webhook (name, receiving URL, numbers to watch). The HMAC signing secret is returned only once, in this response.
  • POST /webhook/{id}/subscriptions and DELETE /webhook/{id}/subscriptions: add or remove enterprise or establishment numbers.
  • GET /webhook/{id}/subscriptions: the list of numbers watched by a webhook.
  • POST /webhook/{id}/trigger: sends a test delivery to check your receiver and your signature check.
  • GET /webhook/{id}/events: the log of the last 100 delivery attempts, with status, response code and timestamp.
  • PATCH /webhook/{id}/hmac-secret: rotates the signing secret; the old one stops being valid immediately.

Each event states its type (creation, update or deactivation of the record, or a test delivery), the number concerned and the entity type, and it is signed with the webhook secret. Signature verification is described step by step in the webhooks guide.

Example request#

"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"

Recommended implementation#

  • Verify the signature of each delivery before acting on it, on the raw body of the request.
  • Answer quickly with a 2xx code, then process the event in the background: read the record again with GET /enterprise/{num} to learn its new state.
  • Make processing idempotent: the same delivery can arrive more than once.
  • Add numbers to the webhook when a client or supplier enters your portfolio, and remove them when the relationship ends.
  • Check the delivery log when your receiver was unavailable, and trigger a test delivery after each deployment.

Limits to know#

  • Events follow the updates published by the BCE: they arrive after a change is recorded in the register, not at the moment of the decision.
  • A webhook signals that a record changed; to know the new value of a field, read the record again.
  • Failed deliveries are retried, but a receiver that stays unavailable can miss events: the log of the last 100 attempts helps you find them.
  • Webhooks watch specific numbers. They do not report new companies in a sector or a region.

Frequently asked questions#

Which changes trigger a webhook?

The creation, update or deactivation of the record of a watched company or establishment, as published by the BCE, plus the test deliveries you trigger.

How do I secure the receiver?

Each delivery is HMAC-signed with the webhook secret. Verify the signature on the raw body before processing the event, and rotate the secret if it leaks.

Can I monitor establishments?

Yes. Subscriptions accept both enterprise and establishment numbers.

Put it into practice

Create a key in the developer portal, then follow the reference documentation for each endpoint mentioned.

Get an API keyRead the documentation

Reference documentation

  • Webhooks guide
  • Webhooks API

Other use cases

  • Check a client or supplier before working with them
  • Enrich a CRM automatically from the company number
  • Validate a VAT number (VIES) when entering an invoice
  • KYC/KYB when opening a business account

On this page

The problemThe API data that answers itExample requestRecommended implementationLimits to knowFrequently asked questionsPut it into practice
API BCEAPI BCE

A developer product by Espero-Soft Informatiques, built on official BCE/KBO open data.

Product

Use casesWhy API BCEPricingFAQ

Developers

DocumentationAPI ReferenceAPI PlaygroundChangelogGet API key

Company

Data, compliance and Peppol ↗Company Belgium ↗Espero-Soft ↗

Legal

Legal noticeTerms of ServicePrivacy PolicyCookie Policy
© 2026 Espero-Soft Informatiques SRL · All rights reserved.Made in Belgium 🇧🇪