Unternehmen per Webhook überwachen
Einen Dritten einmal zu prüfen reicht nicht: Ein Kunde zieht um, ein Lieferant stellt den Betrieb ein. Webhooks benachrichtigen Sie, statt Sie die API abfragen zu lassen.
Das Problem#
Ein Bestand an Kunden oder Lieferanten altert. Adressen ändern sich, Bezeichnungen entwickeln sich, Unternehmen stellen den Betrieb ein. Die erste Idee ist, die API jede Nacht für jedes Unternehmen im Bestand abzufragen: Das kostet Kontingent, und die meisten Antworten ändern nichts.
Webhooks kehren die Logik um: Sie geben einmal die zu überwachenden Nummern an, und die API ruft Ihren Server auf, wenn sich ein überwachter Datensatz im Register ändert.
Die API-Daten, die antworten#
POST /webhook: legt einen Webhook an (Name, Empfangs-URL, zu überwachende Nummern). Das HMAC-Signatur-Secret wird nur einmal zurückgegeben, in dieser Antwort.POST /webhook/{id}/subscriptionsundDELETE /webhook/{id}/subscriptions: fügen Unternehmens- oder Niederlassungsnummern hinzu oder entfernen sie.GET /webhook/{id}/subscriptions: die Liste der von einem Webhook überwachten Nummern.POST /webhook/{id}/trigger: sendet eine Testzustellung, um Ihren Empfänger und Ihre Signaturprüfung zu testen.GET /webhook/{id}/events: das Protokoll der letzten 100 Zustellversuche mit Status, Antwortcode und Zeitstempel.PATCH /webhook/{id}/hmac-secret: erneuert das Signatur-Secret; das alte ist sofort ungültig.
Jedes Event nennt seinen Typ (Anlage, Änderung oder Deaktivierung des Datensatzes oder eine Testzustellung), die betroffene Nummer und den Entitätstyp, und es ist mit dem Secret des Webhooks signiert. Die Prüfung der Signatur ist Schritt für Schritt im Webhook-Leitfaden beschrieben.
Beispielanfrage#
"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"Empfohlene Umsetzung#
- Prüfen Sie die Signatur jeder Zustellung, bevor Sie darauf reagieren, und zwar auf dem Roh-Body der Anfrage.
- Antworten Sie schnell mit einem 2xx-Code und verarbeiten Sie das Event danach im Hintergrund: Lesen Sie den Datensatz mit
GET /enterprise/{num}erneut, um seinen neuen Stand zu kennen. - Gestalten Sie die Verarbeitung idempotent: Dieselbe Zustellung kann mehr als einmal ankommen.
- Fügen Sie Nummern zum Webhook hinzu, wenn ein Kunde oder Lieferant in Ihren Bestand kommt, und entfernen Sie sie, wenn die Beziehung endet.
- Sehen Sie im Zustellprotokoll nach, wenn Ihr Empfänger nicht erreichbar war, und lösen Sie nach jedem Deployment eine Testzustellung aus.
Grenzen, die Sie kennen sollten#
- Events folgen den von der BCE veröffentlichten Aktualisierungen: Sie kommen an, nachdem eine Änderung im Register eingetragen wurde, nicht zum Zeitpunkt der Entscheidung.
- Ein Webhook meldet, dass sich ein Datensatz geändert hat; um den neuen Wert eines Feldes zu kennen, lesen Sie den Datensatz erneut.
- Fehlgeschlagene Zustellungen werden wiederholt, aber ein dauerhaft nicht erreichbarer Empfänger kann Events verpassen: Das Protokoll der letzten 100 Versuche hilft, sie wiederzufinden.
- Webhooks überwachen bestimmte Nummern. Sie melden keine neuen Unternehmen in einer Branche oder Region.
Häufige Fragen#
Welche Änderungen lösen einen Webhook aus?
Die Anlage, Änderung oder Deaktivierung des Datensatzes eines überwachten Unternehmens oder einer Niederlassung, wie von der BCE veröffentlicht, sowie die von Ihnen ausgelösten Testzustellungen.
Wie sichere ich den Empfänger ab?
Jede Zustellung ist mit dem Secret des Webhooks HMAC-signiert. Prüfen Sie die Signatur auf dem Roh-Body, bevor Sie das Event verarbeiten, und erneuern Sie das Secret, wenn es offengelegt wurde.
Kann ich Niederlassungen überwachen?
Ja. Abonnements akzeptieren sowohl Unternehmens- als auch Niederlassungsnummern.
In die Praxis umsetzen
Erstellen Sie einen Schlüssel im Entwicklerportal und folgen Sie dann der Referenzdokumentation für jeden genannten Endpunkt.
Referenzdokumentation