Webhook: racconta ad altri strumenti cosa è successo

#Che cos'è un webhook

Pensalo come il tuo progetto che telefona a un altro servizio per dire cosa è appena successo. Dai a Briks un indirizzo (un URL che ti ha dato l'altro strumento), scegli gli eventi da comunicare, e ogni volta che ne accade uno Briks invia un messaggio a quell'indirizzo. Molti strumenti di automazione, di gestione clienti e componenti aggiuntivi per fogli di calcolo possono darti un indirizzo del genere.

Tecnicamente, ogni messaggio è una richiesta POST: una chiamata che porta con sé un corpo, qui scritto in JSON, un formato di testo semplice che i programmi sanno leggere. Lo strumento che lo riceve legge il corpo e fa ciò che hai impostato.

record.changed segue le modifiche fatte nello studio: un record aggiunto, modificato o eliminato nella scheda Database, una raccolta svuotata o il database ripristinato. I record che il sito online salva da sé, come una richiesta di prenotazione inviata da un visitatore, non lo attivano.

form.received viene inviato sia per le voci dell'anteprima sia per quelle della produzione. Ogni messaggio indica quale delle due è, così l'altro strumento può ignorare le voci dell'anteprima.

#Limiti di ogni piano

Quando le chiamate del giorno sono esaurite, una consegna non viene inviata e viene contrassegnata come Failed con il messaggio: Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.

Quando un progetto ha tutti i webhook che il suo piano consente, Add webhook diventa grigio e un link Get more accanto al conteggio apre la finestra di upgrade, che indica il piano più piccolo con spazio per un altro.

#Aggiungi un webhook

Ogni webhook dell'elenco mostra il suo indirizzo, la nota e gli eventi, con quale segreto è firmato (i primi caratteri) e come è andata l'ultima consegna. Il suo interruttore lo imposta su On o Off, e i suoi tre puntini contengono Send a test event (fino a dieci all'ora, solo quando è attivo), Change, New signing secret e Delete.

#Come appare una consegna

Ogni invio ha le stesse tre parti: type (il codice dell'evento), timestamp (quando è avvenuto, in UTC) e data (i dettagli). Ecco una voce di modulo:

Ogni consegna include anche tre header: webhook-id (l'id del messaggio), webhook-timestamp (quando è stato inviato, in secondi) e webhook-signature. Seguono il formato aperto Standard Webhooks, quindi gli strumenti che lo capiscono possono verificare le consegne per te.

#Verifica che una consegna sia autentica

Chiunque può inviare un messaggio a un indirizzo, quindi chi riceve dovrebbe controllare la firma prima di fidarsi. La firma è creata con il segreto di firma che hanno solo tu e Briks. Quando un progetto ha un webhook, la pagina Webhooks mostra un breve esempio di codice sotto Checking a delivery is genuine. In parole, il controllo funziona così:

1. Prendi il corpo esattamente come è arrivato, come testo, prima di leggerlo come JSON.
2. Unisci webhook-id, webhook-timestamp e il corpo con dei punti fermi tra l'uno e l'altro.
3. Prendi il tuo secret, togli whsec_ all'inizio e decodifica il resto da base64. Quella è la chiave.
4. Firma il testo unito con HMAC SHA-256 e quella chiave, scrivi il risultato in base64 e metti v1, davanti.
5. La consegna è autentica se coincide con uno dei valori separati da spazio in webhook-signature e il timestamp è entro cinque minuti da adesso.

Una consegna che viene ritentata mantiene il suo webhook-id, così il destinatario può conservare gli id già gestiti e saltare i duplicati.

#Consegne e nuovi tentativi

Deliveries elenca ogni consegna degli ultimi trenta giorni, dalla più recente. Restringi l'elenco con Status e premi Show. Clicca su una consegna per vedere il messaggio completo, l'eventuale errore e la risposta dell'indirizzo.

Ogni tentativo attende una risposta fino a 15 secondi. Se la risposta non è un 2xx, Briks riprova: cinque tentativi in tutto, il primo subito e poi dopo circa 30 secondi, 2 minuti, 8 minuti e 32 minuti, quindi circa 45 minuti dal primo all'ultimo. Una risposta 410 (gone) interrompe subito i tentativi. I reindirizzamenti non vengono seguiti, quindi indica l'indirizzo finale.

Quando una consegna è Failed o Delivered, Send again invia lo stesso messaggio con lo stesso id, firmato di nuovo. Il webhook deve essere attivo.

#Approfondimenti e impostazioni

Insights riassume gli ultimi trenta giorni: Deliveries, la quota Delivered, Failed after every try (con il numero di tentativi necessari) e il tempo Average answer. Sotto, By event e By address mostrano dove si concentrano gli errori.

Settings ha Download JSON sotto Download the webhooks, con indirizzo, eventi e nota di ogni webhook. I segreti di firma non sono mai inclusi. La sua zona pericolosa contiene Clear log, che elimina il registro delle consegne e interrompe ogni nuovo tentativo, e Delete all, che rimuove ogni webhook dopo che hai scritto il nome del progetto. Entrambi sono riservati a Owner e Admin.

#Esempio pratico: le voci dei moduli in un altro strumento

Le voci dei moduli non si possono esportare dallo studio, quindi un webhook è il modo per conservarle in un altro strumento man mano che arrivano. Le conserva anche lo studio: le ultime 100 compaiono in Settings, Forms.