Webhook: Collegare SuperSaaS ad Altre Applicazioni Web

I webhook sono notifiche HTTP di un evento accaduto in SuperSaaS (trigger) inviate ad altre applicazioni web, che innescano in queste ultime delle azioni conseguenti (action). Il contenuto di tali notifiche è definito dall'utente. I webhook facilitano lo scambio di informazioni tra applicazioni web.

Alcuni esempi di webhook (T=trigger, A=action):

Loghi Webhook

Configurare automaticamente i webhook con Zapier.com

Il sito Zapier.com ti permette di collegare tra di loro in maniera interattiva centinaia di applicazioni web, tra cui SuperSaaS, senza dover scrivere una riga di codice. Zapier offre una versione di prova e un abbonamento base gratuito.

Creare degli “Zap”, ovvero dei collegamenti tra applicazioni web, a partire da modelli già pronti non presenta particolari difficoltà; di seguito trovi comunque informazioni dettagliate nel caso tu voglia avere maggiore controllo sugli eventi da collegare.

Nuovo utente inserito in lista MailChimpNuovo utente → lista MailChimp
Nuovo appuntamento inserito in Google CalendarNuovo appuntamento → Google Calendar
Nuovo appuntamento genera fattura in QuickBooksNuovo appuntamento → fattura QuickBooks
Nuovo appuntamento genera email con filtroNuovo appuntamento → filtro email

Trigger supportati

Puoi utilizzare tre categorie di oggetti (utente, appuntamento e modulo), e per ciascuna di esse puoi gestire l'evento “Nuovo” o “Modifica”. Quest'ultimo include qualsiasi modifica, quindi anche gli eventi “Nuovo” e “Cancella”.

TriggerCausato da…
New userSi attiva quando un nuovo utente si registra sul tuo account
Changed userSi attiva quando un utente, o l'amministratore per lui, modifica i dati inseriti in sede di registrazione
New appointmentSi attiva quando un utente, o l'amministratore, inserisce un appuntamento in uno specifico calendario
Changed appointmentSi attiva per ogni possibile modifica all'appuntamento, inclusi gli eventi “Nuovo”, “Cancella”, “Confermato da lista d'attesa”, “Pagamento ricevuto”, etc. (vedi sotto la lista completa)
New stand-alone formSi attiva quando viene inviato un modulo personalizzato (utilizzato come componente a sé)
Updated stand-alone formSi attiva per ogni possibile modifica a un modulo personalizzato (utilizzato come componente a sé)

Da notare che se hai configurato il tuo calendario prenotazioni in modo da non richiedere la registrazione all'utente non vedrai mai un trigger "Nuovo utente", ma solo uno "Nuovo appuntamento".

Filtrare gli eventi

Quando colleghi due applicazioni web, Zapier ti permette di filtrare gli eventi. Di seguito alcuni esempi:

Quando crei un nuovo "Zap" il sito Zapier ti richiede di definire un oggetto presente in SuperSaaS. Di tale oggetto vengono elencati i campi disponibili. I campi che verranno inviati dal webhook dipendono da quelli attivi nel tuo account ed eventualmente dalla presenza o meno di un modulo personalizzato. I campi “trigger” e “role” sono sempre inclusi e possono essere utili per filtrare gli eventi. Per esempio, potresti filtrare soltanto i trigger che contengono il valore “delete” nel campo "event".

TriggerPossibili valori del campo "event"
Nuovo utentenew
Utente modificatonew, change, delete
Nuovo appuntamentocreate
Appuntamento modificatocreate, edit, place, pending, destroy, restore, approve, revert
Nuovo modulonew
Modulo modificatonew, change, delete, restore

Campo "Role"Chi ha attivato l'evento…
0AnonimoNon loggato
1Loggato con password condivisa
2Validato con verifica di intervallo IP
3Utente standard
4Superuser
5Amministratore o Rivenditore
7Sistema o Gateway di pagamento

Configurazione manuale dei webhook

Nota: questa opzione è disponibile solo per gli abbonati. Puoi provarla per una settimana cliccando il pulsante "Inizia prova gratuita" sulla pagina dedicata ai webhook.

Creare un webhook senza l'aiuto di Zapier richiede alcune competenze di sviluppo web. La restante parte di questa pagina contiene informazioni per sviluppatori che intendono creare un webhook per inviare dati alla propria applicazione web, o che vogliono sviluppare un'interfaccia tra SuperSaaS e un altro sito.

Puoi creare e aggiornare manualmente i webhook sull'omonima pagina del tuo account.

Un webhook invia dati, quindi richiede che dall'altra parte sia attivo un servizio web in grado di riceverli. Tipicamente l'altra parte è un sito web creato da te, ma può anche essere un sito di terze parti al quale il webhook si connette.

Personalizzare il messaggio inviato dal webhook

Di default un webhook invia tutti i campi rilevanti in formato JSON. Nota che se a un oggetto è collegato un modulo personalizzato, anche i campi di quest'ultimo verranno inclusi. Puoi modificare tale impostazione affinché non venga inviato alcun dato, o affinché vengano inviati soltanto i dati che hai definito tu. Ad esempio, potresti voler includere nel messaggio una qualche API key o parametro di autenticazione.

Dopo aver creato un nuovo webhook arriverai automaticamente a una pagina dove è possibile modificare i contenuti del "payload", ovvero il messaggio inviato dal webhook. Selezionando l'opzione "Personalizza" comparirà un editor JSON che ti permetterà di aggiungere o rimuovere campi specifici. La parte inferiore dell'editor elenca tutti i campi disponibili che vengono valorizzati quando il messaggio viene generato. I campi disponibili cambiano in funzione di quelli abilitati per quello specifico oggetto.

Provare un webhook

Un buon sito che può aiutarti a effetuare il debug di un webhook è RequestBin. Tale servizio ti fornisce un link che puoi utilizzare come target URL per controllare esattamente quali dati vengono inviati dal webhook.

Sulla pagina di modifica trovi anche un link “Prova webhook” che ti permette di attivare manualmente un webhook ed eventualmente modificare il messaggio da inviare. In questo modo puoi, ad esempio, simulare un pagamento fallito senza doverlo realmente eseguire nel tuo calendario prenotazioni.

Il messaggio di prova viene inviato circa 5 secondi dopo essere stato creato. Se la parte ricevente risponde con un codice di stato diverso da "OK" (ovvero al di fuori dell'intervallo di codici compreso tra 200 e 300) il messaggio verrà inviato nuovamente a intervalli di tempo crescenti. Dopo 10 tentativi falliti il messaggio verrà cancellato e se un webhook ha più di 5 messaggi falliti diviene inattivo fintanto che non verrà manualmente riattivato dalla pagina dei webhook. Se la parte ricevente risponde con un codice di stato "410 Gone" il webhook verrà immediatamente cancellato.