Ondernemingen opvolgen met webhooks
Een derde één keer controleren volstaat niet: een klant verhuist, een leverancier stopt. Webhooks verwittigen je in plaats van je de API te laten bevragen.
Het probleem#
Een portefeuille van klanten of leveranciers veroudert. Adressen veranderen, benamingen evolueren, ondernemingen stoppen. Het eerste idee is om elke nacht de API te bevragen voor elke onderneming in de portefeuille: dat kost quota, en de meeste antwoorden veranderen niets.
Webhooks keren de logica om: je geeft één keer de op te volgen nummers op, en de API roept je server aan wanneer een opgevolgde fiche in het register wijzigt.
De API-gegevens die antwoorden#
POST /webhook: maakt een webhook aan (naam, ontvangst-URL, op te volgen nummers). Het HMAC-ondertekeningssecret wordt maar één keer teruggegeven, in dit antwoord.POST /webhook/{id}/subscriptionsenDELETE /webhook/{id}/subscriptions: voegen ondernemings- of vestigingsnummers toe of verwijderen ze.GET /webhook/{id}/subscriptions: de lijst van nummers die een webhook opvolgt.POST /webhook/{id}/trigger: stuurt een testlevering om je ontvanger en je controle van de handtekening na te gaan.GET /webhook/{id}/events: het logboek van de laatste 100 leveringspogingen, met status, antwoordcode en tijdstip.PATCH /webhook/{id}/hmac-secret: vervangt het ondertekeningssecret; het oude is meteen ongeldig.
Elk event vermeldt zijn type (aanmaak, wijziging of deactivering van de fiche, of een testlevering), het betrokken nummer en het type entiteit, en het is ondertekend met het secret van de webhook. De controle van de handtekening wordt stap voor stap beschreven in de webhookgids.
Voorbeeldverzoek#
"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"Aanbevolen aanpak#
- Controleer de handtekening van elke levering voor je er iets mee doet, op de ruwe body van het verzoek.
- Antwoord snel met een 2xx-code en verwerk het event daarna op de achtergrond: lees de fiche opnieuw met
GET /enterprise/{num}om haar nieuwe toestand te kennen. - Maak de verwerking idempotent: dezelfde levering kan meer dan eens aankomen.
- Voeg nummers toe aan de webhook wanneer een klant of leverancier je portefeuille binnenkomt, en verwijder ze wanneer de relatie eindigt.
- Raadpleeg het leveringslogboek wanneer je ontvanger onbereikbaar was, en verstuur een testlevering na elke uitrol.
Grenzen om te kennen#
- Events volgen de updates die de KBO publiceert: ze komen aan nadat een wijziging in het register is ingeschreven, niet op het moment van de beslissing.
- Een webhook meldt dat een fiche wijzigde; om de nieuwe waarde van een veld te kennen, lees je de fiche opnieuw.
- Mislukte leveringen worden opnieuw geprobeerd, maar een ontvanger die lang onbereikbaar blijft, kan events missen: het logboek van de laatste 100 pogingen helpt je ze terug te vinden.
- Webhooks volgen precieze nummers op. Ze melden geen nieuwe ondernemingen in een sector of een regio.
Veelgestelde vragen#
Welke wijzigingen activeren een webhook?
De aanmaak, wijziging of deactivering van de fiche van een opgevolgde onderneming of vestiging, zoals gepubliceerd door de KBO, plus de testleveringen die je zelf verstuurt.
Hoe beveilig ik de ontvanger?
Elke levering is HMAC-ondertekend met het secret van de webhook. Controleer de handtekening op de ruwe body voor je het event verwerkt, en vervang het secret bij een lek.
Kan ik vestigingen opvolgen?
Ja. Abonnementen aanvaarden zowel ondernemings- als vestigingsnummers.
Aan de slag
Maak een sleutel aan in het ontwikkelaarsportaal en volg daarna de referentiedocumentatie voor elk vermeld endpoint.
Referentiedocumentatie