Webhook nella sezione “Avatar video”: notifica al tuo server quando il video è pronto
Webhook nella sezione "Avatar video" è un modo per scoprire che il video è pronto, senza aggiornare manualmente la pagina: non appena il video è stato completato, viene inviata una richiesta POST all'indirizzo del tuo server e il tuo server stesso decide cosa fare dopo: scrivere il collegamento al database, inviare il file al client o avviare il passaggio successivo. La scheda serve a chi realizza video in batch o integra la generazione di avatar nel proprio prodotto: invece di infiniti controlli "pronto o non ancora", arriva una breve notifica esattamente al momento giusto.
Perché è necessario?
Il rendering di un video non è un'operazione immediata e non ha senso attenderlo in una scheda aperta. Secondo le misurazioni della piattaforma del 07/09/2026, un video Kling 3.0 di cinque secondi in 1080p è considerato in media 115 secondi e nel 95% dei casi rientra in 165. Per Sora 2, la stessa attività richiede in media circa 145 secondi. Se controlli lo stato ogni pochi secondi, in un video appaiono dozzine di richieste vuote; Il webhook arriva solo una volta, quando viene effettivamente visualizzato il risultato.
Anche il volume parla da solo. Secondo il registro di generazione della piattaforma, in 30 giorni (3 settembre – 2 ottobre 2026), sono state avviate 3.292 attività video, di cui 2.369 completate con successo. I video vengono conteggiati in background e terminano in momenti diversi: questo non può essere monitorato manualmente e un accurato gestore delle notifiche risolve il problema stesso.
Cosa fa la scheda “Webhook”?
Si tratta di inviare notifiche, senza magia. Registi un indirizzo, scegli a quali eventi iscriverti e ricevi un segreto di iscrizione. L'elenco degli endpoint registrati è archiviato proprio lì: puoi vedere l'indirizzo, gli eventi selezionati, lo stato e se l'endpoint ha un segreto. Il segreto può essere rilasciato nuovamente (quello vecchio smetterà immediatamente di funzionare) oppure l'endpoint può essere completamente eliminato.
L’evento nasce solo dai tuoi video: il video di qualcun altro non uscirà, anche se è stato conteggiato nello stesso momento. C'è anche un registro degli eventi consegnati: è comodo verificare che qualcosa abbia effettivamente raggiunto il tuo server.
Come iniziare: passo dopo passo
- Sezione aperta "Avatar video" e pannello webhook all'indirizzo diretto /ru/avatar?tab=webhook.
- Accedi al tuo account: l'impostazione non è disponibile per gli ospiti; quando viene cliccato, si aprirà una finestra di accesso.
- Nel campo "Indirizzo endpoint", inserisci l'indirizzo HTTPS pubblico del tuo server, ad esempio https://example.com/avatar-webhook. HTTP non funzionerà: la consegna e la firma sono progettate per un canale sicuro.
- Contrassegnare gli eventi richiesti. Se non selezioni nulla, sarai iscritto a tutti gli eventi contemporaneamente.
- Fare clic su "Aggiungi endpoint". Subito dopo la creazione apparirà il segreto dell'abbonamento: copialo e salvalo tu stesso: non verrà più visualizzato.
- Se non hai ancora il tuo server, fai clic su "Sostituisci il nostro ricevitore": le notifiche verranno accumulate nel registro degli eventi consegnati direttamente nella scheda.
Come essere sicuri che la richiesta provenga da noi e non sia un falso
Ogni richiesta è accompagnata da un'intestazione della firma: si tratta di HMAC-SHA256, calcolato dal corpo grezzo della richiesta come segreto. Dalla tua parte conta la stessa firma e confronta: se non corrisponde scartiamo la richiesta. Il nostro ricevitore fa esattamente questo e risponde con 401 ad una firma errata. Mantieni il segreto sul server, nelle variabili di ambiente e non nel codice client.
Cosa c'è nella richiesta
Il corpo è un semplice JSON con il tipo di evento e i dati dell'entità. Ad esempio, per un video finito, questo è l'evento BLK0 con l'identificatore del video al suo interno. L'elenco completo delle tipologie di eventi disponibili è mostrato nella scheda: puoi ordinarlo e lasciare solo ciò di cui il tuo servizio ha realmente bisogno.
Quanto costa?
La registrazione dell'endpoint, il nuovo rilascio segreto, l'eliminazione e il registro eventi non cancellano i token: si tratta di un'impostazione di notifica, non di una generazione. I token vengono spesi solo per il video stesso: il prezzo in token è visibile prima del lancio e, se l'attività fallisce, viene restituito quanto cancellato. Non è previsto alcun abbonamento: ai nuovi utenti vengono assegnati gettoni di partenza per i primi test.
Con cosa abbinare
- "Attività batch" — lanciare dozzine di video con un compito; Un webhook eliminerà la necessità di un controllo manuale della disponibilità.
- "Mediateca" — archiviazione dei codici sorgente e dei file finiti.
- "Traduzione video" E "Taglio clip" - passi successivi dopo la generazione.
Domande frequenti
Quale indirizzo è adatto per un webhook?
Solo HTTPS pubblico. Non sono accettati indirizzi locali e HTTP: la notifica deve passare su un canale sicuro e il tuo server deve essere accessibile dall'esterno.
È possibile ricevere notifiche se non è presente un server?
SÌ. Fai clic su "Sostituisci il nostro ricevitore": gli eventi verranno accumulati nel registro "Eventi consegnati" nella scheda, potranno essere visualizzati senza il tuo backend.
Cosa fare se la firma non corrisponde?
Verifica di stare leggendo HMAC-SHA256 dal corpo della richiesta grezza (e non dal JSON analizzato) e di utilizzare il segreto corrente: dopo la riemissione, quello vecchio smette immediatamente di funzionare.
Questo è pagato?
La configurazione dei webhook non cancella i token. I token vengono spesi solo per la generazione di video: il loro prezzo è visibile prima del lancio; Non è previsto alcun abbonamento, ai nuovi utenti vengono assegnati gettoni iniziali.