Cos'è un webhook e come funzionano i webhook di sona.to

Un webhook è un messaggio che un'app invia a un'altra nel momento in cui succede qualcosa, così la seconda app non deve continuare a chiedere. Dai un indirizzo alla prima app, che ci invia i dettagli di ogni evento appena si verifica. Questa guida spiega come funzionano i webhook, come controllare che un webhook sia autentico e cosa invia sona.to, come riassume anche la pagina Webhooks.

Cos'è un webhook?

La maggior parte delle app condivide dati in due modi. Con un'API, il tuo sistema chiede: «il post è già stato pubblicato?», e chiede di nuovo più tardi se la risposta è no. Con un webhook, è l'app ad avvisarti: quando il post viene pubblicato, invia una richiesta all'indirizzo che hai scelto, con i dettagli del post.

Un webhook è quindi una richiesta HTTP, di solito un POST con un corpo JSON, inviata a un URL che controlli tu. Quell'URL può essere il tuo server, oppure un indirizzo webhook fornito da n8n, Zapier, Make, Slack o un altro servizio che avvia un flusso quando arriva la richiesta.

Webhook e API: le differenze

Un'API serve a chiedere e a modificare: elencare post, creare un post, leggere dati. Un webhook serve a essere avvisati. La maggior parte delle integrazioni usa entrambi: l'API per creare un post e un webhook per sapere quando è stato pubblicato o non è andato a buon fine. Interrogare un'API più e più volte spreca richieste e porta comunque a saperlo tardi, mentre un webhook arriva appena l'evento accade.

Come verificare un webhook

Chiunque conosca l'indirizzo del tuo webhook potrebbe inviargli una richiesta falsa, quindi un webhook fatto bene è firmato. Il mittente calcola una firma a partire dal corpo e da un segreto condiviso, di solito con HMAC SHA-256, e la inserisce in un header. Dal tuo lato calcoli la stessa firma con lo stesso segreto e confronti le due con un confronto a tempo costante. Se sono diverse, la richiesta viene ignorata.

Includere un timestamp nei dati firmati impedisce anche i replay: una richiesta intercettata una volta non può essere reinviata più tardi, perché il suo timestamp è troppo vecchio.

I webhook in sona.to

sona.to invia webhook per quattro eventi: un post è stato pubblicato, un post non è andato a buon fine, un audit del sito è terminato e un audit del sito non è andato a buon fine. Scegli quali eventi riceve ogni webhook, così un avviso in chat può ascoltare solo gli errori mentre un foglio di report riceve tutto. Il payload usa gli stessi nomi dei campi dell'API di sona.to.

Configurazione. Nella pagina API della tua dashboard, incolla l'indirizzo, spunta gli eventi e salva. Il segreto di firma viene mostrato una sola volta in quel momento, quindi copialo subito.

Firma. Ogni consegna contiene un header con un timestamp e un HMAC SHA-256 del timestamp e del corpo, creato con il tuo segreto. Rifiuta le richieste il cui timestamp ha più di qualche minuto.

Nuovi tentativi. Se il tuo indirizzo non è raggiungibile o restituisce un errore, la consegna viene ritentata dopo 60 secondi, 5 minuti e 30 minuti. Ogni tentativo viene registrato con il suo codice di stato e la sua durata. Un indirizzo che continua a fallire viene disattivato, e puoi riattivarlo una volta risolto il problema.

Sicurezza. L'indirizzo deve usare https e puntare a un server pubblico. Gli indirizzi su reti private vengono rifiutati al salvataggio e di nuovo al momento della consegna, e i reindirizzamenti non vengono seguiti.

Webhook con n8n, Zapier e Make

Le app di sona.to per n8n, Zapier e Make hanno trigger pronti per gli stessi quattro eventi, quindi non devi incollare tu un indirizzo: aggiungi il trigger e l'app configura il webhook. Leggi l'automazione social con n8n, Zapier e Make.

Tutti i dettagli, con un esempio di verifica della firma, sono nella documentazione dell'API.

Domande frequenti

Un webhook è la stessa cosa di un'API?

No. Un'API risponde quando chiedi. Un webhook ti invia un messaggio quando succede qualcosa.

I webhook di sona.to sono gratuiti?

I webhook sono inclusi in ogni piano, insieme all'API.

Cosa succede se il mio server non è raggiungibile?

sona.to ritenta tre volte nell'arco di circa mezz'ora. Se le consegne continuano a fallire, il webhook viene disattivato finché non lo riattivi.