Automatizza Transept con i trigger webhook

Apra un workflow salvato nel costruttore e osservi la scheda del trigger in alto — quella con la dicitura Lo esegui manualmente. È un interruttore. Manuale è l'impostazione predefinita: sarà Lei a premere Esegui. Webhook assegna al workflow un URL privato a cui un sistema esterno invia una richiesta POST, così l'esecuzione si avvia automaticamente. Un trigger appartiene a un workflow salvato, quindi lo salvi prima — l'opzione Webhook rimane disabilitata su una bozza non salvata.

Imposti la scheda su Webhook, definisca su cosa agisce l'attivazione (sotto) e salvi. Transept genera un URL segreto per questo singolo Workflow e lo mostra una sola volta: lo copi subito, perché viene memorizzato solo un hash e l'URL completo non potrà mai più essere visualizzato. Il segreto risiede nell'URL anziché in un header, poiché i sistemi di invio più semplici non possono impostare header; tratti quindi l'URL come una password: chiunque lo possieda può avviare l'esecuzione.

Riaprendo la scheda in un secondo momento, vedrà un prefisso mascherato (whk_live_…) al posto dell'URL completo, oltre all'azione Ruota. La rotazione genera un nuovo URL e invalida quello precedente nell'istante in cui conferma: è così che si revoca un link trapelato. Può anche disattivare il trigger senza eliminarlo, o rimuoverlo del tutto. La scheda mostra l'ultima attivazione.

Due impostazioni determinano su cosa interviene il workflow quando l'URL viene richiamato:

• Destinazione — un documento fisso specificato (ogni attivazione viene indirizzata a quel documento e al relativo gruppo linguistico), oppure la pagina Notion indicata nel payload in entrata (Transept la associa al Suo documento, importandola la prima volta che viene rilevata).
• Lingue — tutte le versioni linguistiche (l'impostazione predefinita; l'esecuzione si estende a ogni lingua della destinazione come esecuzione di gruppo), o solo il singolo documento.
• Solo contenuti aggiornati — attivo per impostazione predefinita, perché un'esecuzione automatizzata dovrebbe rielaborare solo ciò che è cambiato dall'ultima volta, senza tradurre nuovamente l'intero documento a ogni attivazione. Consulti Esegui solo ciò che è cambiato.

Un'automazione del database di Notion può richiamare il trigger con l'azione Invia webhook: indirizzi l'azione verso l'URL del trigger e, ogni volta che l'automazione viene eseguita, Transept esegue il Workflow sulla pagina che l'ha attivata. Ci sono due aspetti da conoscere prima di farvi affidamento.

Innanzitutto, le automazioni di Notion si attivano in seguito alla modifica di una proprietà (o alla creazione di una nuova pagina), non alla sola modifica del corpo del testo — pertanto, la modifica del testo di una pagina potrebbe non attivare nulla. Il metodo più affidabile consiste nell'utilizzare una proprietà Stato monitorata dall'automazione: ne cambi il valore (ad esempio in Pronto per la traduzione) e quella modifica fungerà da segnale.

In secondo luogo, un webhook di Notion identifica solo la pagina — non ne trasmette mai il contenuto — quindi Transept legge la pagina tramite la Sua connessione Notion, a cui deve essere garantito l'accesso al database all'interno di Notion. Entrambi i passaggi (connettere Notion e poi condividere il database con l'integrazione) sono descritti nella sezione “Trigger di Notion: consenti l'accesso a Transept” di Automatizzare Transept con l'API. Se ne tralascia uno, ogni attivazione verrà respinta con un errore di accesso.

Qualsiasi sistema in grado di inviare un POST HTTP può azionare il trigger: un passaggio di Zapier o n8n, un job CI o un comando curl al termine di una build. Per una destinazione documento fisso, il corpo della richiesta non è rilevante e basta un POST vuoto; solo la destinazione pagina Notion legge il corpo per individuare la pagina modificata. Non serve l'header Authorization: l'intero URL funge da chiave segreta.

Per impostazione predefinita, un'attivazione esegue il workflow su tutte le versioni linguistiche e — con l'opzione Solo contenuti aggiornati attiva — traduce nuovamente solo i blocchi il cui testo originale è cambiato dall'ultima esecuzione; così una piccola modifica costa solo una manciata di blocchi, non l'intero documento. Le esecuzioni avviate in questo modo scalano le parole esattamente come nell'editor in-app: se il saldo non è sufficiente a coprire l'operazione, non viene inviato nulla e non viene addebitato alcun costo.

Un passaggio impostato su attesa di revisione si arresta comunque: l'attivazione traduce fino a quel punto e poi si ferma; la lingua comparirà nel pannello «Revisioni pronte» dell'editor per l'approvazione. L'automazione non scavalca i controlli di revisione. Inoltre, quando una destinazione pagina Notion non può essere letta (solitamente perché il database non è stato condiviso con l'integrazione), la scheda del trigger segnala l'ultimo errore con la nota «impossibile leggere la pagina Notion», completa di timestamp, per chiarire perché l'attivazione non ha prodotto risultati.