Configurare i webhook

Con una chiave API è un altro programma a recuperare i Suoi dati quando gli servono. Con un webhook è il contrario: siamo noi a inviare un messaggio a un Suo indirizzo non appena succede qualcosa.

Questo evita di aspettare. Un ordine che arriva alle otto e un quarto è nella Sua contabilità alle otto e un quarto — e non al giro successivo, un'ora dopo.

A cosa serve ai nostri clienti:

• ogni vendita subito in contabilità o in un database proprio;
• un piccolo schermo all'ingresso che mostra chi è appena entrato;
• un messaggio in una chat di gruppo non appena una visita guidata è esaurita;
• una propria e-mail o un sms all'acquirente, oltre al nostro.

Questo articolo è la guida alla schermata, passo dopo passo. Se prima vuole sapere che cos'è un webhook e se Le serve, legga Webhook.

Da sapere: i webhook fanno parte dello stesso piano dell'API. Su un piano più piccolo Accesso API non compare nel Suo menu; se arriva comunque sulla schermata, vede una spiegazione e un pulsante Vai all'abbonamento.

Dove andare

Apra nel menu a sinistra Impostazioni → Accesso API e clicchi in alto sulla scheda Webhook. Solo il ruolo Proprietario vede questa schermata.

Vede tre blocchi: Siamo noi a chiamarLa (spiegazione), Nuova destinazione (il modulo) e Destinazioni (quelle che esistono già).

Che cosa Le serve

Una cosa sola, e deve esserci prima di iniziare: un indirizzo sul Suo server in grado di ricevere messaggi. È un po' di lavoro di programmazione dalla Sua parte — il Suo sviluppatore o il Suo gestionale capirà se dice "un endpoint per i webhook".

Tre requisiti:

1. Deve essere https. Un normale indirizzo http lo rifiutiamo: su quella linea passano dati di acquirenti.
2. Deve essere raggiungibile dall'esterno. Un indirizzo all'interno della Sua rete d'ufficio (qualcosa con 192.168. o 10.) non possiamo raggiungerlo, e lo rifiutiamo.
3. Deve rispondere in fretta. Aspettiamo dieci secondi. Se l'elaborazione richiede più tempo, faccia rispondere subito "ok" al Suo server e lavori dopo.

Aggiungere una destinazione

Passo 1. Inserisca l'indirizzo. Nel primo campo (https://...) l'indirizzo completo a cui possiamo inviare, ad esempio https://contabilita.miaazienda.it/webhooks/biglietti.

Passo 2. Dica a cosa serve. Il secondo campo (A cosa serve?) non è obbligatorio, ma comodo. "La nostra contabilità", "schermo alla cassa". Se ne ha tre, sa subito quale serve a cosa.

Passo 3. Selezioni su cosa possiamo avvisarLa. L'elenco si trova sotto Su cosa vuole essere avvisato?. È la scelta più importante. Selezioni solo ciò che elabora davvero: ogni messaggio che non usa è lavoro per il Suo server e rumore nel Suo registro. Almeno una casella deve essere spuntata; una destinazione senza messaggi non riceverebbe mai nulla.

Messaggio	Quando parte
Ordine creato	È nato un ordine (un carrello non conta).
Ordine pagato	Il denaro è arrivato.
Ordine annullato	L'ordine è stato annullato o è scaduto.
Ordine rimborsato	C'è stato un rimborso totale o parziale.
Biglietto emesso	È stato emesso un biglietto.
Biglietto scansionato	C'è stata una scansione all'ingresso — anche se rifiutata.
Biglietto annullato	Un biglietto è stato annullato o rimborsato.
Fascia oraria esaurita	Una fascia oraria è piena.
Fascia oraria di nuovo libera	C'è di nuovo posto in una fascia oraria piena.
Buono regalo emesso	È stato venduto un buono.
Buono regalo utilizzato	È stato scalato un importo da un buono.
Abbonamento emesso	È stato creato un abbonamento annuale.
Sessione di cassa chiusa	Un cassetto di cassa è stato contato e chiuso.
Fattura emessa	È stata creata una fattura o una nota di credito per un acquirente.

Passo 4 (facoltativo). Destinazione di test. Se l'indirizzo punta a un ambiente di prova, spunti Destinazione di test (riceve solo eventi di test). Maggiori dettagli sotto "Una destinazione di test" più in basso.

Passo 5. Clicchi su Aggiungi destinazione.

Può avere fino a venti destinazioni. Se ne ha già venti, ne elimini prima una.

Il segreto lo vede una volta sola

Subito dopo compare un segreto: una lunga sequenza che inizia con whsec_.

Lo copi ora e lo passi a chi costruisce il collegamento. Se aggiorna la pagina o cambia scheda, è sparito.

Con quel segreto firmiamo ogni messaggio che inviamo al Suo indirizzo. Il Suo server può così verificare che il messaggio arrivi davvero da noi e non da qualcuno che ha intercettato il Suo indirizzo. Non è un lusso: senza quella verifica il Suo endpoint è una porta aperta in cui chiunque può infilare ordini.

Ha perso il segreto? Clicchi su Nuovo segreto. Ne riceve subito uno nuovo e quello vecchio smette di funzionare da quel momento — non dimentichi quindi di sostituirlo anche dall'altra parte.

Per chi costruisce il collegamento, il portale per sviluppatori spiega esattamente come ricalcolare quella firma, con esempi in PHP, JavaScript e Python. Tramite l'API può anche richiedere un messaggio di esempio firmato per testare il proprio codice, senza dover prima fare una vendita.

Testare senza una vendita

Clicchi accanto a una destinazione su Messaggio di prova. Inviamo allora un solo messaggio di tipo test.ping — nessun dato reale, solo un segnale.

Sotto si apre subito il registro dei messaggi, così vede che cosa ha risposto il Suo server. Se compare Consegnato, funziona. Se compare un codice di errore, sa dove guardare. Un messaggio di prova parte anche verso una destinazione disattivata.

Il registro dei messaggi

Clicchi accanto a una destinazione su Messaggi. Vede gli ultimi cinquanta messaggi e, per ognuno:

• di che tipo era e quando è partito;
• che cosa ha restituito il Suo server (il numero è lo stato http; 200 significa "ok");
• quante volte abbiamo provato;
• a che punto è: Consegnato, In arrivo (stiamo ancora provando) o Non consegnato.

Se un messaggio non è arrivato, può riproporlo con Riprova. Comodo dopo aver risolto un guasto dalla Sua parte.

I messaggi restano trenta giorni. Poi vengono ripuliti: il registro serve a trovare un problema, non come archivio.

Cosa succede se il Suo server non risponde

Non ci arrendiamo subito. Se un messaggio non arriva, riproviamo sei volte, con intervalli sempre più lunghi: dopo un minuto, cinque minuti, mezz'ora, due ore, dodici ore e un giorno. In tutto, ben più di un giorno e mezzo.

Se ancora non funziona:

• la destinazione riceve il contrassegno Non arriva;
• riceve un'e-mail. Va all'E-mail di contatto della Sua organizzazione o, se è vuota, all'Indirizzo di fatturazione (e-mail) (entrambi in Impostazioni → Organizzazione, scheda Contatto);
• la destinazione resta attiva. Gli eventi successivi vengono riproposti e non appena arriva qualcosa il contrassegno sparisce.

Riceve al massimo una di queste e-mail al giorno per destinazione. Un server fermo per un intero weekend non produce quindi cento e-mail.

Una destinazione di test

Selezioni Destinazione di test alla creazione quando l'indirizzo punta a un ambiente di prova. Una destinazione così riceve solo eventi di test — ciò che accade agli ordini di prova di una chiave di test — e mai vendite reali. Nell'elenco porta il contrassegno Test. Al contrario, una destinazione normale non riceve mai nulla da un ordine di prova.

Questa separazione è netta, e di proposito: un server di test che elabora per errore un ordine reale invia una conferma a un acquirente reale.

Disattivare o eliminare

Disattiva ferma le consegne ma lascia la destinazione, con il suo segreto e il suo registro; porta il contrassegno Disattivato. Comodo durante una manutenzione dalla Sua parte. Clicchi di nuovo su Attiva e riparte.

Elimina rimuove la destinazione e il suo registro. Non è reversibile; una nuova destinazione riceve un nuovo segreto.

C'è un terzo caso: se il Suo server risponde con il codice 410, disattiviamo noi stessi la destinazione. Quel codice significa letteralmente "questo indirizzo non esiste più", e continuare a bussare sarebbe scortese. Lo stesso accade quando l'indirizzo nel frattempo punta a una rete interna. Clicchi su Attiva appena è tutto a posto.

Tre consigli per chi costruisce il collegamento

1. Prima risponda, poi elabori. Dica subito "ok" e faccia il lavoro vero in background. Altrimenti si scontra con i nostri dieci secondi.
2. Elabori in modo idempotente. Ogni messaggio porta un proprio numero (l'Idempotency-Key). Se lo stesso numero arriva due volte, non faccia nulla. Noi riproviamo in caso di dubbio, e una doppia prenotazione è peggio di una doppia riga di registro.
3. Non conti sull'ordine. Due messaggi possono sorpassarsi quando il primo viene ripetuto. Guardi l'ora nel messaggio e il suo contenuto, non l'ordine di arrivo.

Per saperne di più

• Webhook — che cos'è un webhook e quando Le serve, senza termini tecnici.
• Creare una chiave API — l'altra scheda di questa schermata.
• Il portale per sviluppatori — per chi costruisce il collegamento.