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}/subscriptionsandDELETE /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.
Reference documentation