Dit artikel is voor studiomanagers die bsport-gebeurtenissen naar andere tools sturen. Het behandelt het aanmaken, testen, pauzeren en bijwerken van webhooks in Instellingen. Voor API-sleutels, zie "Je API-sleutels beheren".

Overzicht

Een webhook laat een andere tool weten wanneer er iets gebeurt in bsport. Wanneer een klant een les boekt of er een factuur wordt aangemaakt, stuurt bsport de details naar een webadres dat jij kiest. Je rapportagetool, CRM of automatiseringsplatform kan daar dan meteen op reageren, zonder steeds opnieuw bsport te hoeven controleren.

Beheer al je webhooks vanaf één pagina: Instellingen > Webhooks (te vinden onder Integraties).

De pagina heet Webhooks & API's en heeft twee tabbladen: Webhooks en API. Dit artikel behandelt het tabblad Webhooks.

Webhooks bestaan in verschillende versies:

V2 is de huidige versie en degene die je aanmaakt.
V1 en Legacy zijn oudere versies die nog steeds gebeurtenissen versturen totdat je ze vervangt (zie "Oudere webhooks: V1 en Legacy" hieronder).

Wie het kan gebruiken: managers wiens rol de Webhook-toestemming heeft. Vraag de beheerder van je studio om dit voor jouw rol in te schakelen.

Wat je kunt doen

Een webhook aanmaken voor één gebeurtenis en één eindpunt-URL.
De gebeurtenis of de URL van een webhook bewerken.
Een test versturen om te controleren of je tool gebeurtenissen ontvangt.
Een webhook pauzeren en later weer hervatten.
Het ondertekeningsgeheim van een webhook kopiëren of vernieuwen.
Oudere webhooks (V1 en Legacy) vervangen door V2-webhooks.
De lijst filteren op Alle, Actief of Gepauzeerd.

Veelvoorkomende toepassingen

Hoe je nieuwe boekingen naar een andere tool stuurt

Ga naar Instellingen > Webhooks en selecteer Webhook aanmaken.
Zoek bij Gebeurtenis naar booking.created en kies deze.
Voer bij Eindpunt-URL het adres van je tool in, bijvoorbeeld https://example.com/webhooks/bsport.
Selecteer Webhook aanmaken.

De webhook is meteen actief. Maak één webhook per gebeurtenis aan: om boekingen te volgen die worden gewijzigd of verwijderd, voeg je booking.updated en booking.deleted toe.

Hoe je controleert of je tool gebeurtenissen ontvangt

Selecteer het verzendicoon (Webhook testen) op de rij van de webhook. bsport stuurt één voorbeeldlevering met voorbeeldgegevens naar je URL en toont het resultaat:

Resultaat	Wat het betekent
Afgeleverd	Je tool reageerde met een succesvolle status.
De ontvanger antwoordde met een fout	Je tool heeft het voorbeeld ontvangen, maar antwoordde met een foutstatus. De statuscode wordt getoond.
Geen reactie	bsport kreeg geen antwoord: de tool reageerde niet op tijd, kon niet worden bereikt, de URL verwijst niet naar een openbaar adres, of het certificaat werd geweigerd.

Als je te vaak test, vraagt bsport je om een minuut te wachten voordat je opnieuw test.

Hoe je een webhook pauzeert

Pauzeer een webhook om te voorkomen dat bsport de bijbehorende gebeurtenis naar je tool stuurt, zonder de webhook te verwijderen. De gebeurtenis, URL en het ondertekeningsgeheim blijven bewaard.

Gebruik dit terwijl je tool niet beschikbaar is of wordt bijgewerkt, of nadat je een V1-webhook door een V2-webhook hebt vervangen.

Om te pauzeren, zet je de schakelaar Actief uit op de rij van de webhook (selecteer op een telefoon in plaats daarvan Webhook pauzeren)

Er wordt niets verstuurd zolang de webhook is gepauzeerd.

Om opnieuw te starten, zet je de schakelaar weer aan, of selecteer je Webhook hervatten.

Hoe je je tool beschermt tegen nepgebeurtenissen

Elke webhook heeft een Ondertekeningsgeheim, dat verborgen wordt weergegeven met de laatste 4 tekens zichtbaar. Je tool gebruikt dit om te controleren of een gebeurtenis echt van bsport komt. Selecteer het kopieericoon om het geheim naar je tool te kopiëren.

Om het geheim te vervangen, selecteer je het vernieuwingsicoon (Geheim vernieuwen) en bevestig je dit. Het huidige geheim werkt meteen niet meer, ook voor nieuwe pogingen. Werk je tool meteen bij met het nieuwe geheim.

Hoe het werkt

Instellen. Maak een webhook aan met een gebeurtenis en een openbare URL. Gebruik een adres dat begint met https:// of http://. Lokale en privéadressen worden geweigerd.
Normaal gebruik. Telkens wanneer de gebeurtenis zich voordoet in bsport, stuurt bsport de naam van de gebeurtenis, de datum en de gegevens naar je URL. De lijst met gebeurtenissen en de inhoud van elke levering staan in de Webhooks-documentatie (ook gelinkt rechtsboven op de pagina).
Wijzigingen. Bewerk de gebeurtenis of URL met het potloodicoon (Webhook bewerken), en selecteer daarna Wijzigingen opslaan.
Pauzeren of geheim wijzigen. Pauzeer om leveringen te stoppen. Vernieuw het geheim als je denkt dat het is gelekt.

Gebeurtenissen waaruit je kunt kiezen

De lijst met gebeurtenissen kan veranderen. De Webhooks-documentatie is altijd actueel en beschrijft elke gebeurtenis en wat bsport verstuurt. Controleer dit voordat je een gebeurtenis kiest.

28 gebeurtenissen verdeeld over 11 bronnen. Elke gebeurtenisnaam bestaat uit de bron, gevolgd door wat er is gebeurd.

Bron	Gebeurtenissen
Boeking	`booking.created`, `booking.updated`, `booking.deleted`
Les	`class.created`, `class.updated`
Klant	`client.created`, `client.updated`, `client.tag_added`, `client.tag_removed`
Docent	`teacher.created`, `teacher.updated`, `teacher.deleted`
Factuur	`invoice.created`, `invoice.updated`
Afspraak	`appointment.created`, `appointment.updated`, `appointment.canceled`
Dienst	`service.created`, `service.updated`
Vestiging	`venue.created`, `venue.updated`, `venue.deleted`
Lessenkaart	`class_pass.created`, `class_pass.updated`
Lessenkaart van klant	`client_class_pass.created`, `client_class_pass.updated`
Product	`product.created`, `product.updated`

Belangrijk gedrag

Eén actieve webhook per gebeurtenis en URL

bsport weigert een tweede actieve webhook die dezelfde gebeurtenis naar dezelfde URL stuurt. Om een gepauzeerde webhook te hervatten die een actieve webhook zou dupliceren, pauzeer je eerst de actieve webhook.

Oudere webhooks: V1 en Legacy

Je lijst kan oudere webhooks naast V2-webhooks tonen. Een gele banner telt de oudere webhooks die nog steeds gebeurtenissen versturen ("bij te werken"). Deze stoppen binnenkort met werken, dus zet elke webhook om naar V2.

Type	Waar het verschijnt	Wat je kunt doen
V2	Tabel Webhooks, Versie V2	Testen, bewerken, pauzeren, het geheim kopiëren of vernieuwen.
V1	Tabel Webhooks, Versie V1	Pauzeren, of Bijwerken naar V2. Geen vernieuwing van het geheim.
Legacy	Tabel Legacy-webhooks	Bijwerken naar V2, of Uitschakelen. Geen pauzeren, geen ondertekeningsgeheim.

Een V1-webhook overzetten:

Selecteer Bijwerken naar V2 op de bijbehorende rij. Het formulier opent met de overeenkomende V2-gebeurtenis en dezelfde URL.
Kies Welke webhook moet gebeurtenissen ontvangen?
- V1 pauzeren: de nieuwe V2-webhook ontvangt gebeurtenissen.
- V1 laten draaien: de nieuwe V2-webhook start gepauzeerd. Hervat deze zodra je tool klaar is.
Selecteer Webhook aanmaken.

Een Legacy-webhook overzetten: selecteer Bijwerken naar V2 en maak de V2-webhook aan. De Legacy-webhook blijft actief totdat je Uitschakelen selecteert.

Uitschakelen is definitief. Het verwijdert de Legacy-webhook permanent, en de bijbehorende gebeurtenis wordt niet meer verstuurd. Om die gebeurtenis opnieuw te ontvangen, maak je een V2-webhook aan.
Geen V2-vervanging. Gebeurtenissen voor abonnementen hebben geen V2-equivalent, dus Bijwerken naar V2 is hiervoor uitgeschakeld. Zie de Migratiegids voor Legacy-webhooks en de Migratiegids voor V1-webhooks.

Wie wat ziet

Iedereen met de Webhook-toestemming ziet het tabblad Webhooks. Het tabblad API is apart en beperkt tot Eigenaren en Beheerders. Zie "Je API-sleutels beheren".

Veelgestelde vragen

Ik zie Instellingen > Webhooks niet. Waarom?

Je rol heeft niet de Webhook-toestemming. Vraag de beheerder van je studio om deze aan jouw rol toe te voegen.

Kan ik een V2-webhook verwijderen?

Nee. Pauzeer de webhook in plaats daarvan. Een gepauzeerde webhook verstuurt niets.

Waarom wordt mijn URL geweigerd?

De URL moet openbaar zijn en beginnen met https:// of http://. Lokale en privéadressen, zoals localhost, worden geweigerd.

De test toont "Geen reactie". Wat moet ik controleren?

Controleer of je tool actief is, of de URL openbaar is en of het certificaat geldig is. Test daarna opnieuw.

Kan ik het volledige ondertekeningsgeheim zien?

De tabel toont alleen de laatste 4 tekens. Gebruik het kopieericoon om het volledige geheim te kopiëren.

Waarom kan ik het geheim van een V1-webhook niet vernieuwen?

Vernieuwen is alleen voor V2-webhooks. Maak een V2-webhook aan om een vernieuwbaar geheim te krijgen.

Je webhooks beheren