Come ricevere notifiche con i webhook?
Un webhook è una notifica automatica: ogni volta che un cliente fa qualcosa (ti scrive in chat, completa un allenamento, commenta un esercizio…), TrainerStudio chiama un indirizzo web (un URL) che gli indichi tu. Così il tuo agente IA, la tua automazione Zapier o Make, o il tuo sistema lo sanno subito, senza dover chiedere ogni pochi minuti.
Non serve saper programmare: lo strumento che vuoi collegare ti dà un URL e tu lo incolli in TrainerStudio. I dettagli tecnici sono nella documentazione per sviluppatori (in inglese).
1. Apri la scheda Webhook
Vai su La tua app → Sviluppatori nel menu laterale (la trovi anche in Impostazioni → Sviluppatori) e apri la scheda Webhook.
Solo il titolare dell'account può gestire i webhook.
2. Aggiungi un endpoint
Un endpoint è l'URL che riceve le notifiche.
- Premi Aggiungi endpoint.
- In URL dell'endpoint, incolla l'indirizzo che ti ha dato il tuo strumento. Deve iniziare con
https://. - In Descrizione, scrivi qualcosa che ti aiuti a riconoscerlo: «Zapier, nuovi messaggi», «Agente IA».
- Scegli cosa vuoi ricevere:
- Tutti gli eventi: ricevi tutto, anche i tipi di evento che aggiungeremo in futuro.
- Solo gli eventi che scelgo: selezioni quelli che ti interessano.
- Salva.
Puoi avere fino a 10 endpoint. Creane uno per strumento: se smetti di usarne uno, elimini solo il suo.
Eventi disponibili
| Evento | Quando viene inviato |
|---|---|
| Messaggio di chat ricevuto | Un cliente ti scrive nella chat dell'app |
| Allenamento completato | Un cliente completa l'allenamento del giorno |
| Commento su un allenamento | Un cliente lascia un commento, una foto o un video su un esercizio |
| Metrica registrata | Viene registrato un valore in una metrica di un cliente |
| Attività completata | Un cliente completa un'attività |
| Foto dei progressi caricata | Un cliente carica una foto dei progressi |
| Modulo compilato | Un cliente risponde a un modulo |
La notifica dice cosa è successo e a quale cliente, ma non include il contenuto (né il testo del messaggio né le misure). Il tuo strumento consulta i dettagli con il proprio accesso al tuo account.
3. Copia il secret di firma
Quando crei l'endpoint compare la finestra Copia il tuo secret di firma. Il secret (inizia con whsec_) permette al tuo strumento di verificare che la notifica arrivi davvero da TrainerStudio.
- Viene mostrato solo questa volta. Copialo e incollalo nel tuo strumento prima di premere L'ho copiato.
- Se il tuo strumento non chiede un secret (succede con molte automazioni semplici), puoi proseguire senza usarlo.
- Se lo perdi, ruota il secret e ne avrai uno nuovo.
4. Invia un evento di prova
Nella pagina dell'endpoint, premi Invia evento di prova. In pochi secondi vedi come ha risposto il tuo strumento:
- Consegnato: funziona tutto.
- Fallito: vedi il motivo (l'URL non risponde, impiega più di 10 secondi, restituisce un errore…). Controlla l'URL nel tuo strumento e riprova.
5. Controlla gli invii
La pagina di ogni endpoint mostra:
- Le statistiche degli ultimi 7 o 30 giorni: percentuale di successo, tempo di risposta e invii al giorno.
- Il Registro degli invii: ogni notifica inviata negli ultimi 30 giorni. Aprine una per vedere i tentativi, la risposta del tuo strumento e il contenuto esatto inviato.
- Invia di nuovo: reinvia una notifica fallita, per esempio dopo aver sistemato il tuo strumento.
Se un invio fallisce, TrainerStudio riprova da solo fino a 8 volte in poco più di un giorno, aspettando ogni volta di più. Non devi fare nulla.
6. Ruota il secret se lo perdi
Nella pagina dell'endpoint, premi Ruota secret. Ricevi un nuovo secret e, per 24 ore, le notifiche sono firmate sia con il nuovo sia con il precedente: hai questo tempo per cambiarlo nel tuo strumento senza perdere notifiche.
7. Disattiva o elimina un endpoint
- Disattiva smette di inviare notifiche a quell'endpoint e annulla quelle in attesa. Puoi premere Attiva di nuovo quando vuoi. Gli eventi che avvengono mentre è disattivato non vengono inviati dopo.
- Elimina endpoint lo rimuove del tutto. Non si può annullare.
Se TrainerStudio lo disattiva da solo
Un endpoint viene disattivato automaticamente quando:
- non accetta nessun invio da 3 giorni, oppure
- il tuo strumento risponde che quell'indirizzo non esiste più.
Vedrai un avviso con il motivo nella pagina dell'endpoint. Risolvi il problema nel tuo strumento e premi Riattiva.
Cosa conviene sapere
- Tratta l'URL e il secret come una password. Non condividerli e non pubblicarli.
- Un endpoint per strumento, con una descrizione chiara.
- La stessa notifica può arrivare due volte se c'è stato un nuovo tentativo. Gli strumenti robusti ne tengono conto; tienilo presente se usi un'automazione semplice.
- Le notifiche possono arrivare in disordine. Ognuna riporta l'ora in cui è avvenuto l'evento.
- Vuoi solo parlare con i tuoi dati da ChatGPT o Claude? Non ti servono i webhook: segui le guide dedicate.