API BCE Webhooks: Änderungen an Unternehmen verfolgen
Webhooks der API BCE: Erhalten Sie ein HMAC-signiertes Ereignis, sobald sich ein beobachtetes Unternehmen in der BCE ändert. Anlage, Inhalt, Prüfung.
Webhooks push changes to you instead of you polling. Subscribe a webhook to one or more enterprises and CompanyBelgium POSTs a signed event to your URL whenever a watched record changes. You create and manage them through the Webhooks API.
How it works#
- Create a webhook with a target
urland the entity numbers to watch. - Store the
hmacSecretreturned at creation: it is shown only once. - We POST a JSON event to your URL on every change; respond with
2xxquickly to acknowledge it.
Event payload#
{
"event": "update",
"entityNumber": "1033022383",
"entityType": "enterprise",
"data": "...",
"timestamp": "..."
}Verify the signature#
Every delivery carries an X-CompanyBelgium-Signature header of the form sha256=<hex>: the HMAC-SHA256 of <timestamp>.<raw body>, keyed with your webhook secret, where the timestamp is the X-CompanyBelgium-Timestamp header (Unix milliseconds). Recompute it and compare in constant time before trusting the event; rejecting timestamps older than 5 minutes protects against replays.
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();
}Retries & delivery log#
A delivery that gets a 5xx, a network error or no answer within 10 seconds is retried up to 3 times. The most recent attempts are available from the delivery-log endpoint, and you can send a test event at any time.
Treat the HMAC secret like a password. If it leaks, rotate it from the Webhooks API: the old secret stops working immediately.
Create a 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"]
}'Monitoring mit Webhooks der API BCE aufbauen#
Webhooks lohnen sich, sobald Sie Unternehmen dauerhaft beobachten. Ein Kreditversicherer möchte zum Beispiel wissen, wenn sich die Lage eines Kunden ändert. Ein Einkaufsteam überwacht dagegen seine wichtigsten Lieferanten. Statt jede Nummer täglich abzufragen, abonnieren Sie diese Nummern einmal. Das spart außerdem Kontingent.
Einen Empfänger zuverlässig bauen
Ihr Endpunkt sollte schnell mit 2xx antworten. Legen Sie das Ereignis deshalb zuerst in eine Warteschlange und verarbeiten Sie es danach. Eine Zustellung ohne Antwort innerhalb von 10 Sekunden gilt nämlich als fehlgeschlagen. Sie wird dann bis zu dreimal wiederholt. Ihr Code muss daher mit doppelten Ereignissen umgehen können.
- Die Signatur über den rohen Body prüfen, nie über ein neu serialisiertes JSON.
- Zeitstempel ablehnen, die älter als 5 Minuten sind.
- Ereignisse idempotent verarbeiten, etwa über
entityNumberundtimestamp. - Nach dem Ereignis den aktuellen Datensatz über
/enterprise/{num}nachladen. - Das HMAC-Secret nur in einem Secret-Speicher ablegen.
Betrieb und Fehlersuche#
Senden Sie nach dem Anlegen zuerst eine Testzustellung. So prüfen Sie Erreichbarkeit und Signaturprüfung, bevor echte Ereignisse eintreffen. Kommt nichts an, lesen Sie das Zustellprotokoll. Es zeigt Antwortcode, Wiederholungen und Fehlermeldung jedes Versuchs. Ein Fehler 401 Ihres Servers deutet zum Beispiel auf ein falsches Secret hin.
Wird das Secret bekannt, erneuern Sie es sofort. Das alte Secret verliert dann unmittelbar seine Gültigkeit. Tauschen Sie es deshalb gleichzeitig in Ihrem Empfänger aus. Für Wartungsfenster können Sie einen Webhook außerdem pausieren, statt ihn zu löschen.
Ein Ablauf aus der Praxis
Ein Einkaufsteam abonniert zum Beispiel seine 200 wichtigsten Lieferanten. Trifft ein Ereignis ein, prüft der Empfänger zuerst die Signatur. Danach legt er das Ereignis in eine Warteschlange. Ein Hintergrunddienst lädt dann den aktuellen Datensatz und vergleicht Status und Rechtslage. Hat sich etwas geändert, erhält der zuständige Einkäufer eine Meldung. So reagiert das Team, bevor eine offene Rechnung zum Risiko wird.
Testen Sie diesen Ablauf schließlich mit einer Testzustellung, bevor Sie echte Nummern abonnieren.
Überwachen Sie außerdem Ihren Empfänger selbst. Fällt er länger aus, endet jede Zustellung nach höchstens drei Wiederholungen. Gleichen Sie deshalb nach einem Ausfall die betroffenen Unternehmen einmal vollständig über die API ab. So schließen Sie jede Lücke in Ihren Daten.
Halten Sie außerdem fest, welche Unternehmen ein Webhook beobachtet. Diese Liste brauchen Sie für den Abgleich nach einem Ausfall.
Häufige Fragen zu Webhooks der API BCE#
Welcher Tarif enthält Webhooks der API BCE?
Webhooks gehören zum Tarif API Pro. Im Testmodus sind sie noch nicht verfügbar.
Wie oft wird eine fehlgeschlagene Zustellung wiederholt?
Bis zu dreimal, wenn Ihr Server mit 5xx antwortet, ein Netzwerkfehler auftritt oder 10 Sekunden lang keine Antwort kommt.
Was enthält ein Ereignis?
Die Felder event, entityNumber, entityType, data und timestamp. Die Verwaltung beschreibt die Webhooks-API.