Automatizzare Transept con i trigger webhook

Apri un workflow salvato nel builder e osserva la scheda del trigger in alto — quella con la dicitura Lo esegui manualmente. È un selettore. Manuale è l'impostazione predefinita: sei tu a premere Esegui. Webhook assegna al workflow un URL privato verso cui un sistema esterno invia una richiesta POST, così l'esecuzione si avvia da sola. Il trigger è associato a un workflow salvato, quindi salva prima il workflow — l'opzione Webhook rimane disabilitata sulle bozze non salvate.

Imposta la scheda su Webhook, stabilisci su cosa deve agire l'esecuzione (vedi sotto) e salva. Transept genera un URL segreto per questo specifico workflow e lo mostra una sola volta — copialo subito, perché viene memorizzato solo un hash e l'URL completo non potrà più essere visualizzato. Il segreto si trova nell' URL anziché in un header, poiché i sistemi di invio più semplici non consentono di configurare gli header; tratta quindi l'URL come una password: chiunque ne sia in possesso può avviare l'esecuzione.

Riaprendo la scheda in seguito, vedrai un prefisso oscurato (whk_live_…) al posto dell'URL completo, oltre all'azione Rigenera. La rigenerazione genera un nuovo URL e invalida quello precedente nell'istante in cui confermi: è così che si revoca un link compromesso. Puoi anche disattivare il trigger senza eliminarlo, oppure rimuoverlo del tutto. La scheda indica la data dell'ultima attivazione.

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

• Destinazione — un documento specifico indicato da te (ogni attivazione agisce su quel documento e sul relativo gruppo di lingue), oppure la pagina Notion indicata nel payload in entrata (Transept la associa al tuo documento, importando la pagina la prima volta che la rileva).
• Lingue — tutte le versioni linguistiche (impostazione predefinita; l'esecuzione si estende a ogni lingua della destinazione come esecuzione di gruppo), oppure 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. Vedi Eseguire solo ciò che è cambiato.

Un'automazione del database di Notion può richiamare il trigger tramite l'azione Invia webhook: indirizza l'azione verso l'URL del trigger e, ogni volta che l'automazione viene eseguita, Transept avvia il workflow sulla pagina che l'ha attivata. Ci sono due aspetti da considerare prima di affidarsi a questo sistema.

Primo: le automazioni di Notion si attivano in caso di modifica di una proprietà (o per una nuova pagina), non per la sola modifica del corpo del testo — pertanto, modificare il testo di una pagina potrebbe non attivare nulla. Il metodo più affidabile consiste nell'usare una proprietà Stato monitorata dall'automazione: basta cambiarla (ad esempio in Pronto per la traduzione) e tale modifica fungerà da segnale.

Secondo: i webhook di Notion si limitano a indicare la pagina — non ne trasmettono mai il contenuto — quindi Transept legge la pagina tramite la tua connessione Notion, che deve essere autorizzata ad accedere 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. Basta saltarne uno e ogni attivazione verrà rifiutata con un errore di accesso.

Qualsiasi sistema in grado di inviare una richiesta HTTP POST può attivare il trigger: uno step di Zapier o n8n, un job di CI o un comando curl al termine di una build. Per una destinazione documento specifico, il body non è rilevante, quindi basta un POST vuoto; solo la destinazione pagina Notion legge il body per sapere quale pagina è stata modificata. Non è necessario l'header Authorization: il segreto è l'intero URL.

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 l'editor dell'app e, 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 mette comunque in pausa: l'attivazione traduce fino a quel punto e poi si ferma, e la lingua compare nel pannello Revisioni pronte dell'editor per l'approvazione — l'automazione non scavalca i tuoi punti di controllo. E quando una destinazione pagina Notion non può essere letta (solitamente perché il database non è stato condiviso con l'integrazione), la scheda del trigger riporta l'ultimo errore con la nota “impossibile leggere la pagina Notion”, completa di marca temporale, così puoi capire perché l'attivazione non ha avuto esito.

Sì. Imposta la destinazione del trigger su “il corpo della richiesta è il contenuto” e tutto ciò che invii tramite POST all'URL diventerà il documento: Markdown, HTML o testo semplice in formato grezzo (inviando il relativo Content-Type), oppure un JSON come {"content": "…", "content_type": "markdown"}. Scegli per ogni trigger se ogni invio debba creare un nuovo documento o aggiornare un documento specifico — l'aggiornamento riallinea il contenuto in modo che vengano tradotti nuovamente solo i blocchi modificati. È così che una piattaforma email, un passaggio di Zapier/n8n o qualsiasi script possono inserire un template o un articolo direttamente in un workflow di traduzione senza caricamento manuale. Gli invii ripetuti vengono deduplicati per 24 ore; includi un external_id nel JSON (l'ID del tuo messaggio) per un controllo preciso. Corpo della richiesta fino a 10 MB.