Guide d'intégration
Recevez en temps réel les changements d'entreprises et d'établissements que vous suivez.
Flux complet
- Créez un webhook avec votre URL HTTPS et la liste d'entités à surveiller.
- Conservez précieusement le secret HMAC retourné une seule fois.
- Lors de la prochaine synchro BCE, chaque modification déclenche un POST signé.
- Vérifiez la signature côté receveur avant de traiter le payload.
Créer un webhook
bash
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": "Production listener",
"url": "https://hooks.example.com/companybelgium",
"entityNumbers": ["1033022383", "0202239951"]
}'⚠️ Le champ `hmacSecret` n'est retourné qu'une seule fois à la création. Stockez-le dès maintenant — vous ne pourrez plus le récupérer (uniquement le faire tourner via PATCH /hmac-secret).
Format du payload
http
POST https://hooks.example.com/companybelgium HTTP/1.1
Content-Type: application/json
X-CompanyBelgium-Signature: sha256=8e6c…
X-CompanyBelgium-Timestamp: 1747843200000
X-CompanyBelgium-Event: update
X-CompanyBelgium-Delivery: 9c1b…
{
"event": "update",
"entityNumber": "1033022383",
"entityType": "enterprise",
"data": {},
"timestamp": "2026-04-15T10:00:00.000Z"
}Vérification de la signature
Reconstruisez le HMAC côté receveur avec votre secret + le timestamp et comparez en temps constant.
javascript
import crypto from "node:crypto"
function verify(req, secret) {
const signature = req.headers["x-companybelgium-signature"]
const timestamp = req.headers["x-companybelgium-timestamp"]
const body = req.rawBody // Express: use express.raw() or capture before json()
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${body}`)
.digest("hex")
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
throw new Error("Invalid signature")
}
// Reject signatures older than 5 minutes (replay protection)
if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60_000) {
throw new Error("Timestamp too old")
}
}Politique de retry
Le dispatcher retente jusqu'à 3 fois en cas d'erreur réseau ou 5xx, avec un backoff exponentiel (0,5s → 2s → 8s). Les 4xx ne sont pas retentés. Tous les essais sont visibles dans GET /webhook/{id}/events.
Déclencher un test
Pour vérifier votre intégration sans attendre une vraie modification BCE, utilisez l'endpoint `trigger`.
bash
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/trigger \
-H "X-API-Key: $API_KEY" \
-H "X-API-Secret: $API_SECRET" \
-H "Content-Type: application/json" \
-d '{"entityNumber":"1033022383","data":{"note":"manual test"}}'