Webhook
Un webhook comunica ai tuoi sistemi cosa succede in un workspace: approvazioni, nuovi episodi, video completati, post pubblicati e altro ancora. ShowBits invia ogni evento firmato al tuo indirizzo. I webhook sono disponibili con i piani Enterprise e OnPremise; in tutti i piani, le connessioni per n8n, Zapier e Make hanno webhook propri.
- Configurazione a cura di
- Amministratori del workspace
- Piani
- Enterprise e OnPremise
- Cosa invia ShowBits
- Eventi firmati che indicano gli oggetti con il loro ID, senza nomi, titoli o testi
Aggiungere un webhook
I webhook li aggiungono gli amministratori del workspace. Il tuo sistema ha bisogno di un indirizzo che accetti richieste POST tramite https e sia raggiungibile da internet.
- Apri Settings → API.
- In Webhooks, clicca su Add webhook.
- Inserisci l’indirizzo del tuo sistema in Address (https). Deve iniziare con
https://, non contenere nome utente né password ed essere raggiungibile da internet. - Se vuoi, inserisci una descrizione in Description, ad esempio il nome del sistema.
- In Events, spunta ciò che serve al tuo sistema. La casella di un gruppo, come Clips, spunta tutti i suoi eventi.
- Clicca su Add.
- Clicca su Copy e salva il segreto nel tuo sistema. ShowBits lo mostra solo questa volta.
- Clicca su Done.
Un workspace ha al massimo 10 webhook, compresi quelli delle connessioni per n8n, Zapier e Make. Per n8n, usa il Production URL del nodo Webhook; la finestra di dialogo ti avvisa se inserisci l’URL di test.

Gli eventi e il loro contenuto
Gli eventi sono suddivisi nei gruppi Clips, Episodes, Posts, Quote cards, Team, Integrations, Brand kits e Workspace. Ad esempio: clip.approved quando una clip viene sbloccata, clip.forwarded quando passa alla fase di approvazione successiva, clip.video_ready quando il suo video è pronto, episode.analysed, episode.embargo_ended, post.published, post.failed e clip.delivered per una consegna nel tuo MAM o DAM.
Ogni evento è un POST con un body JSON: id (l’ID dell’evento), type, occurredAt, workspace (ID e slug), object (tipo e ID dell’episodio, della clip o del post), via (app, api, automation o system) e data con pochi campi innocui, come canale o orario. Nomi, titoli e testi non ne fanno mai parte; il tuo sistema recupera i dettagli tramite l’API REST.
Verificare la firma
Ogni evento contiene gli header ShowBits-Event (il tipo dell’evento), ShowBits-Delivery (l’ID della consegna) e ShowBits-Signature: t=…,v1=…. Verifica la firma prima che il tuo sistema agisca in base a un evento.
- Leggi il body della richiesta come testo grezzo, prima che il tuo sistema interpreti il JSON.
- Da
ShowBits-Signature, prendit, l’orario in secondi Unix, e ogni valorev1. - Calcola un HMAC-SHA256 su
t, un punto e il body grezzo, usando come chiave l’intero segreto, compresowhsec_, e scrivi il risultato in esadecimale. - Accetta l’evento solo se il risultato corrisponde a uno dei valori
v1; esegui il confronto in tempo costante. - Scarta l’evento se
trisale a più di cinque minuti fa.
Per un giorno dopo la creazione di un nuovo segreto, l’header contiene un secondo v1, firmato con il segreto precedente. Trovi codice di esempio nella documentazione API.
Testare, mettere in pausa e controllare le consegne
Ogni webhook mostra il suo host, il suo stato (Active, Paused o Paused after failures), la descrizione, il numero di eventi e quando l’indirizzo ha accettato per l’ultima volta un evento.
- Clicca su Test per inviare un evento di prova (
webhook.test). Viene inviato anche a un webhook in pausa. - Clicca su Deliveries per vedere gli ultimi 20 eventi con il loro esito: accettato (con il codice di stato), nuovo tentativo in corso (con il numero di tentativi e l’errore) oppure abbandonato (con l’errore).
- Clicca su Pause per interrompere l’invio degli eventi e su Resume per riprenderlo.
Gli eventi che si verificano mentre un webhook è in pausa non vengono inviati in un secondo momento.

Creare un nuovo segreto
Crea un nuovo segreto se quello vecchio potrebbe essere diventato noto, oppure per cambiarlo di tanto in tanto. Per un giorno firma anche il segreto precedente, così puoi aggiornare il tuo sistema senza interruzioni.
- Nel webhook, clicca su New secret.
- Conferma con New secret.
- Clicca su Copy e salva il nuovo segreto nel tuo sistema.
- Clicca su Done.
Eliminare un webhook
L’eliminazione di un webhook è definitiva: non vi vengono più inviati eventi e le consegne in sospeso vengono annullate.
- Nel webhook, clicca sull’icona del cestino (Delete).
- Conferma con Delete.
Nuovi tentativi, pausa automatica ed eventi ripetuti
Il tuo indirizzo deve rispondere entro 10 secondi con uno stato compreso tra 200 e 299; ShowBits non segue i reindirizzamenti. Altrimenti ShowBits riprova dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore e 24 ore, poi rinuncia a quell’evento. Se l’indirizzo non accetta nulla per tre giorni, ShowBits mette in pausa il webhook (Paused after failures) e invia un’e-mail agli amministratori del workspace. Risolvi il problema all’indirizzo, poi clicca su Resume.
Un evento può arrivare più di una volta: dopo un nuovo tentativo, oppure a due webhook con lo stesso indirizzo. Riconosci le ripetizioni dall’id: è lo stesso per ogni tentativo e per ogni webhook.
Domande
L’indirizzo può trovarsi nella nostra rete interna?
No. ShowBits invia solo a indirizzi https raggiungibili da internet, senza nome utente e password.
Perché un evento non contiene il titolo della clip?
Gli eventi indicano gli oggetti solo con il loro ID, così per questa via nessun nome, titolo o testo esce da ShowBits. Con un token, il tuo sistema recupera i dettagli tramite l’API REST.
Per quanto tempo vengono conservate le consegne?
30 giorni. Deliveries mostra le ultime 20 di un webhook.
Il nostro sistema può gestire da sé i propri webhook?
Sì, tramite l’API REST con un token che abbia i permessi webhooks:read e webhooks:write. La persona a cui appartiene il token deve essere amministratore del workspace.
Abbiamo Creator o Business. Possiamo ricevere eventi?
I webhook in Settings → API sono disponibili con Enterprise e OnPremise. In tutti i piani, le connessioni per n8n, Zapier e Make hanno webhook propri, con la stessa firma: vedi n8n, Zapier e Make.