Questo articolo è per i gestori di studi che inviano eventi bsport ad altri strumenti. Copre la creazione, il test, la pausa e l'aggiornamento dei webhook in Impostazioni. Per le chiavi API, consulta "Gestisci le tue chiavi API".

Panoramica

Un webhook segnala a un altro strumento quando succede qualcosa in bsport. Quando un cliente prenota una lezione o viene creata una fattura, bsport invia i dettagli a un indirizzo web che scegli tu. Il tuo strumento di reporting, CRM o piattaforma di automazione può quindi reagire subito, senza dover controllare bsport continuamente.

Gestisci tutti i tuoi webhook da un'unica pagina: Impostazioni > Webhook (elencati sotto Integrazioni).

La pagina si chiama Webhook e API e ha due schede: Webhook e API. Questo articolo tratta la scheda Webhook.

I webhook esistono in diverse versioni:

V2 è la versione attuale ed è quella che crei.
V1 e Legacy sono versioni più vecchie che continuano a inviare eventi finché non le sostituisci (vedi "Webhook più vecchi: V1 e Legacy" più sotto).

Chi può usarlo: i gestori il cui ruolo ha il permesso Webhook. Chiedi all'amministratore del tuo studio di attivarlo per il tuo ruolo.

Cosa puoi fare

Crea un webhook per un evento e un URL di destinazione.
Modifica l'evento o l'URL di un webhook.
Invia un test per verificare che il tuo strumento riceva gli eventi.
Metti in pausa un webhook e riattivalo in seguito.
Copia o ruota la chiave segreta di firma di un webhook.
Sostituisci i webhook più vecchi (V1 e Legacy) con webhook V2.
Filtra l'elenco per Tutti, Attivi o In pausa.

Casi d'uso comuni

Come inviare le nuove prenotazioni a un altro strumento

Vai su Impostazioni > Webhook e seleziona Crea webhook.
In Evento, cerca e scegli booking.created.
In URL di destinazione, inserisci l'indirizzo del tuo strumento, ad esempio https://example.com/webhooks/bsport.
Seleziona Crea webhook.

Il webhook è attivo subito. Crea un webhook per ogni evento: per seguire le prenotazioni modificate o eliminate, aggiungi booking.updated e booking.deleted.

Come verificare che il tuo strumento riceva gli eventi

Seleziona l'icona di invio (Testa webhook) sulla riga del webhook. bsport invia una consegna di esempio con dati segnaposto al tuo URL e mostra il risultato:

Risultato	Cosa significa
Consegnato	Il tuo strumento ha risposto con uno stato di successo.
Il destinatario ha risposto con un errore	Il tuo strumento ha ricevuto l'esempio ma ha risposto con uno stato di errore. Viene mostrato il codice di stato.
Nessuna risposta	bsport non ha ricevuto risposta: lo strumento è andato in timeout, non è raggiungibile, l'URL non punta a un indirizzo pubblico, oppure il suo certificato è stato rifiutato.

Se testi troppo spesso, bsport ti chiede di aspettare un minuto prima del test successivo.

Come mettere in pausa un webhook

Metti in pausa un webhook per fermare l'invio del suo evento al tuo strumento, senza eliminarlo. Il suo evento, l'URL e la chiave segreta di firma restano salvati.

Usalo quando il tuo strumento non è disponibile o è in fase di aggiornamento, oppure dopo aver sostituito un webhook V1 con uno V2.

Per mettere in pausa, disattiva l'interruttore Attivo sulla riga del webhook (su telefono, seleziona invece Metti in pausa webhook)

Non viene inviato nulla finché il webhook è in pausa.

Per riattivarlo, riattiva l'interruttore, oppure seleziona Riattiva webhook.

Come proteggere il tuo strumento da eventi falsi

Ogni webhook ha una Chiave segreta di firma, mostrata mascherata con gli ultimi 4 caratteri. Il tuo strumento la usa per verificare che un evento provenga davvero da bsport. Seleziona l'icona di copia per copiare la chiave nel tuo strumento.

Per sostituire la chiave, seleziona l'icona di rotazione (Ruota chiave) e conferma. La chiave attuale smette di funzionare immediatamente, inclusi i nuovi tentativi. Aggiorna subito il tuo strumento con la nuova chiave.

Come funziona

Configurazione. Crea un webhook con un evento e un URL pubblico. Usa un indirizzo che inizia con https:// o http://. Gli indirizzi locali e privati vengono rifiutati.
Uso normale. Ogni volta che l'evento si verifica in bsport, bsport invia il nome dell'evento, la sua data e i dati dell'evento al tuo URL. L'elenco degli eventi e il contenuto di ogni consegna si trovano nella documentazione sui webhook (collegata anche in alto a destra nella pagina).
Modifiche. Modifica l'evento o l'URL con l'icona a matita (Modifica webhook), poi seleziona Salva modifiche.
Pausa o cambio di chiave. Metti in pausa per fermare le consegne. Ruota la chiave se pensi che sia stata divulgata.

Eventi disponibili

L'elenco degli eventi può cambiare. La documentazione sui webhook è sempre aggiornata e descrive ogni evento e cosa invia bsport. Consultala prima di scegliere un evento.

28 eventi su 11 risorse. Ogni nome di evento indica la risorsa, seguita da cosa è successo.

Risorsa	Eventi
Prenotazione	`booking.created`, `booking.updated`, `booking.deleted`
Lezione	`class.created`, `class.updated`
Cliente	`client.created`, `client.updated`, `client.tag_added`, `client.tag_removed`
Istruttore	`teacher.created`, `teacher.updated`, `teacher.deleted`
Fattura	`invoice.created`, `invoice.updated`
Appuntamento	`appointment.created`, `appointment.updated`, `appointment.canceled`
Servizio	`service.created`, `service.updated`
Stabilimento	`venue.created`, `venue.updated`, `venue.deleted`
Abbonamento	`class_pass.created`, `class_pass.updated`
Abbonamento del cliente	`client_class_pass.created`, `client_class_pass.updated`
Prodotto	`product.created`, `product.updated`

Comportamenti importanti

Un solo webhook attivo per evento e URL

bsport rifiuta un secondo webhook attivo che invia lo stesso evento allo stesso URL. Per riattivare un webhook in pausa che duplicherebbe uno già attivo, metti prima in pausa quello attivo.

Webhook più vecchi: V1 e Legacy

Il tuo elenco può mostrare webhook più vecchi accanto a quelli V2. Un banner giallo conta i webhook più vecchi che inviano ancora eventi ("da aggiornare"). Smetteranno presto di funzionare, quindi sposta ognuno su V2.

Tipo	Dove appare	Cosa puoi fare
V2	Tabella Webhook, Versione V2	Testa, modifica, metti in pausa, copia o ruota la chiave.
V1	Tabella Webhook, Versione V1	Metti in pausa, oppure Aggiorna a V2. Nessuna rotazione della chiave.
Legacy	Tabella Webhook Legacy	Aggiorna a V2, oppure Disattiva. Nessuna pausa, nessuna chiave segreta di firma.

Per spostare un webhook V1:

Seleziona Aggiorna a V2 sulla sua riga. Si apre il modulo con l'evento V2 corrispondente e lo stesso URL.
Scegli Quale webhook deve ricevere gli eventi?
- Metti in pausa V1: il nuovo webhook V2 riceve gli eventi.
- Mantieni V1 attivo: il nuovo webhook V2 viene creato in pausa. Riattivalo quando il tuo strumento è pronto.
Seleziona Crea webhook.

Per spostare un webhook Legacy: seleziona Aggiorna a V2 e crea il webhook V2. Il webhook Legacy continua a funzionare finché non selezioni Disattiva.

La disattivazione è definitiva. Elimina il webhook Legacy in modo permanente e il suo evento smette di essere inviato. Per ricevere di nuovo quell'evento, crea un webhook V2.
Nessuna sostituzione V2. Gli eventi relativi ai piani di fatturazione non hanno un evento V2 equivalente, quindi Aggiorna a V2 è disattivato per questi. Consulta la guida alla migrazione dei webhook Legacy e la guida alla migrazione dei webhook V1.

Chi vede cosa

Chiunque abbia il permesso Webhook vede la scheda Webhook. La scheda API è separata ed è limitata ai Proprietari e agli Amministratori. Consulta "Gestisci le tue chiavi API".

Domande frequenti

Non vedo Impostazioni > Webhook. Perché?

Il tuo ruolo non ha il permesso Webhook. Chiedi all'amministratore del tuo studio di aggiungerlo al tuo ruolo.

Posso eliminare un webhook V2?

No. Mettilo in pausa invece. Un webhook in pausa non invia nulla.

Perché il mio URL viene rifiutato?

L'URL deve essere pubblico e iniziare con https:// o http://. Gli indirizzi locali e privati, come localhost, vengono rifiutati.

Il test dice "Nessuna risposta". Cosa devo controllare?

Controlla che il tuo strumento sia in funzione, che l'URL sia pubblico e che il suo certificato sia valido. Poi prova di nuovo.

Posso vedere la chiave segreta di firma per intero?

La tabella mostra solo gli ultimi 4 caratteri. Usa l'icona di copia per copiare la chiave completa.

Perché non riesco a ruotare la chiave di un webhook V1?

La rotazione è disponibile solo per i webhook V2. Crea un webhook V2 per ottenere una chiave che può essere ruotata.

Gestisci i tuoi webhook