Dieser Artikel richtet sich an Studioleiter:innen, die bsport-Ereignisse an andere Tools senden. Er behandelt das Erstellen, Testen, Pausieren und Aktualisieren von Webhooks in den Einstellungen. Für API-Schlüssel siehe „Deine API-Schlüssel verwalten".

Überblick

Ein Webhook informiert ein anderes Tool, wenn in bsport etwas passiert. Wenn ein Kunde einen Kurs bucht oder eine Rechnung erstellt wird, sendet bsport die Details an eine von dir gewählte Webadresse. Dein Reporting-Tool, CRM oder Automatisierungstool kann dann sofort reagieren, ohne bsport ständig neu abzufragen.

Verwalte alle deine Webhooks auf einer Seite: Einstellungen > Webhooks (unter Integrationen aufgeführt).

Die Seite heißt Webhooks & APIs und hat zwei Tabs: Webhooks und API. Dieser Artikel behandelt den Tab Webhooks.

Webhooks gibt es in verschiedenen Versionen:

V2 ist die aktuelle Version und diejenige, die du erstellst.
V1 und Legacy sind ältere Versionen, die weiterhin Ereignisse senden, bis du sie ersetzt (siehe „Ältere Webhooks: V1 und Legacy" unten).

Wer es nutzen kann: Manager:innen, deren Rolle die Berechtigung Webhook hat. Bitte die Administration deines Studios, diese für deine Rolle zu aktivieren.

Was du tun kannst

Einen Webhook für ein Ereignis und eine Endpunkt-URL erstellen.
Das Ereignis oder die URL eines Webhooks bearbeiten.
Einen Test senden, um zu prüfen, ob dein Tool Ereignisse empfängt.
Einen Webhook pausieren und später fortsetzen.
Das Signing Secret eines Webhooks kopieren oder rotieren.
Ältere Webhooks (V1 und Legacy) durch V2-Webhooks ersetzen.
Die Liste nach Alle, Aktiv oder Pausiert filtern.

Häufige Anwendungsfälle

So sendest du neue Buchungen an ein anderes Tool

Gehe zu Einstellungen > Webhooks und wähle Webhook erstellen.
Suche unter Ereignis nach booking.created und wähle es aus.
Gib unter Endpunkt-URL die Adresse deines Tools ein, zum Beispiel https://example.com/webhooks/bsport.
Wähle Webhook erstellen.

Der Webhook ist sofort aktiv. Erstelle einen Webhook pro Ereignis: Um Buchungsänderungen oder -löschungen zu verfolgen, füge booking.updated und booking.deleted hinzu.

So prüfst du, ob dein Tool Ereignisse empfängt

Wähle das Sendesymbol (Webhook testen) in der Zeile des Webhooks. bsport sendet eine Beispielübermittlung mit Platzhalterdaten an deine URL und zeigt das Ergebnis an:

Ergebnis	Was es bedeutet
Zugestellt	Dein Tool hat mit einem Erfolgsstatus geantwortet.
Der Empfänger hat mit einem Fehler geantwortet	Dein Tool hat das Beispiel empfangen, aber mit einem Fehlerstatus geantwortet. Der Statuscode wird angezeigt.
Keine Antwort	bsport hat keine Antwort erhalten: Das Tool hat eine Zeitüberschreitung, ist nicht erreichbar, die URL zeigt nicht auf eine öffentliche Adresse, oder das Zertifikat wurde abgelehnt.

Wenn du zu oft testest, bittet dich bsport, vor dem nächsten Test eine Minute zu warten.

So pausierst du einen Webhook

Pausiere einen Webhook, damit bsport sein Ereignis nicht mehr an dein Tool sendet, ohne ihn zu löschen. Ereignis, URL und Signing Secret bleiben gespeichert.

Nutze diese Funktion, während dein Tool ausfällt oder aktualisiert wird, oder nachdem du einen V1-Webhook durch einen V2-Webhook ersetzt hast.

Zum Pausieren schalte den Schalter Aktiv in der Zeile des Webhooks aus (auf dem Smartphone wähle stattdessen Webhook pausieren).

Während der Webhook pausiert ist, wird nichts gesendet.

Um fortzufahren, schalte den Schalter wieder ein oder wähle Webhook fortsetzen.

So schützt du dein Tool vor gefälschten Ereignissen

Jeder Webhook hat ein Signing Secret, das maskiert mit seinen letzten 4 Zeichen angezeigt wird. Dein Tool nutzt es, um zu prüfen, ob ein Ereignis wirklich von bsport stammt. Wähle das Kopiersymbol, um das Secret in dein Tool zu kopieren.

Um das Secret zu ersetzen, wähle das Rotationssymbol (Secret rotieren) und bestätige. Das aktuelle Secret funktioniert sofort nicht mehr, auch nicht für Wiederholungsversuche. Aktualisiere dein Tool sofort mit dem neuen Secret.

So funktioniert es

Einrichtung. Erstelle einen Webhook mit einem Ereignis und einer öffentlichen URL. Verwende eine Adresse, die mit https:// oder http:// beginnt. Lokale und private Adressen werden abgelehnt.
Normale Nutzung. Jedes Mal, wenn das Ereignis in bsport eintritt, sendet bsport den Ereignisnamen, das Datum und die Ereignisdaten an deine URL. Die Liste der Ereignisse und der Inhalt jeder Übermittlung findest du in der Webhooks-Dokumentation (auch oben rechts auf der Seite verlinkt).
Änderungen. Bearbeite das Ereignis oder die URL mit dem Stiftsymbol (Webhook bearbeiten) und wähle dann Änderungen speichern.
Pausieren oder Secret-Änderung. Pausiere, um Übermittlungen zu stoppen. Rotiere das Secret, wenn du vermutest, dass es durchgesickert ist.

Verfügbare Ereignisse

Die Liste der Ereignisse kann sich ändern. Die Webhooks-Dokumentation ist immer aktuell und beschreibt jedes Ereignis sowie dessen Inhalt, den bsport sendet. Prüfe sie, bevor du ein Ereignis auswählst.

28 Ereignisse in 11 Ressourcen. Jeder Ereignisname besteht aus der Ressource, gefolgt davon, was passiert ist.

Ressource	Ereignisse
Buchung	`booking.created`, `booking.updated`, `booking.deleted`
Kurs	`class.created`, `class.updated`
Kund:in	`client.created`, `client.updated`, `client.tag_added`, `client.tag_removed`
Trainer:in	`teacher.created`, `teacher.updated`, `teacher.deleted`
Rechnung	`invoice.created`, `invoice.updated`
Termin	`appointment.created`, `appointment.updated`, `appointment.canceled`
Dienstleistung	`service.created`, `service.updated`
Ort	`venue.created`, `venue.updated`, `venue.deleted`
Class Pass	`class_pass.created`, `class_pass.updated`
Kund:innen-Class-Pass	`client_class_pass.created`, `client_class_pass.updated`
Produkt	`product.created`, `product.updated`

Wichtiges Verhalten

Ein aktiver Webhook pro Ereignis und URL

bsport lehnt einen zweiten aktiven Webhook ab, der dasselbe Ereignis an dieselbe URL sendet. Um einen pausierten Webhook fortzusetzen, der einen aktiven duplizieren würde, pausiere zuerst den aktiven Webhook.

Ältere Webhooks: V1 und Legacy

In deiner Liste können ältere Webhooks neben V2-Webhooks angezeigt werden. Ein gelbes Banner zählt die älteren Webhooks, die noch Ereignisse senden („zu aktualisieren"). Sie werden bald nicht mehr funktionieren, verschiebe also jeden davon zu V2.

Typ	Wo er erscheint	Was du tun kannst
V2	Tabelle Webhooks, Version V2	Testen, bearbeiten, pausieren, das Secret kopieren oder rotieren.
V1	Tabelle Webhooks, Version V1	Pausieren oder Auf V2 aktualisieren. Keine Secret-Rotation.
Legacy	Tabelle Legacy-Webhooks	Auf V2 aktualisieren oder Deaktivieren. Kein Pausieren, kein Signing Secret.

So verschiebst du einen V1-Webhook:

Wähle Auf V2 aktualisieren in seiner Zeile. Das Formular öffnet sich mit dem passenden V2-Ereignis und derselben URL.
Wähle aus: Welcher Webhook soll Ereignisse empfangen?
- V1 pausieren: Der neue V2-Webhook empfängt Ereignisse.
- V1 weiterlaufen lassen: Der neue V2-Webhook startet pausiert. Setze ihn fort, sobald dein Tool bereit ist.
Wähle Webhook erstellen.

So verschiebst du einen Legacy-Webhook: Wähle Auf V2 aktualisieren und erstelle den V2-Webhook. Der Legacy-Webhook läuft weiter, bis du Deaktivieren wählst.

Deaktivieren ist endgültig. Dadurch wird der Legacy-Webhook dauerhaft gelöscht, und sein Ereignis wird nicht mehr gesendet. Um dieses Ereignis wieder zu empfangen, erstelle einen V2-Webhook.
Kein V2-Ersatz. Für Ereignisse des Abrechnungsplans gibt es kein V2-Ereignis, daher ist Auf V2 aktualisieren für sie deaktiviert. Siehe den Migrationsleitfaden für Legacy-Webhooks und den Migrationsleitfaden für V1-Webhooks.

Wer was sieht

Jede Person mit der Berechtigung Webhook sieht den Tab Webhooks. Der Tab API ist separat und nur für Inhaber:innen und Admins zugänglich. Siehe „Deine API-Schlüssel verwalten".

FAQ

Ich sehe Einstellungen > Webhooks nicht. Warum?

Deine Rolle hat nicht die Berechtigung Webhook. Bitte die Administration deines Studios, sie deiner Rolle hinzuzufügen.

Kann ich einen V2-Webhook löschen?

Nein. Pausiere ihn stattdessen. Ein pausierter Webhook sendet nichts.

Warum wird meine URL abgelehnt?

Die URL muss öffentlich sein und mit https:// oder http:// beginnen. Lokale und private Adressen wie localhost werden abgelehnt.

Der Test zeigt „Keine Antwort". Was sollte ich prüfen?

Prüfe, ob dein Tool läuft, ob die URL öffentlich ist und ob das Zertifikat gültig ist. Teste dann erneut.

Kann ich das Signing Secret vollständig sehen?

Die Tabelle zeigt nur die letzten 4 Zeichen. Nutze das Kopiersymbol, um das vollständige Secret zu kopieren.

Warum kann ich das Secret eines V1-Webhooks nicht rotieren?

Die Rotation ist für V2-Webhooks vorgesehen. Erstelle einen V2-Webhook, um ein rotierbares Secret zu erhalten.

Deine Webhooks verwalten