.svg)
.svg)
.svg)
%201Q26_%20GRC%202029.png?width=600&name=(CTA)%201Q26_%20GRC%202029.png)
.svg)
.svg)
Che cos'è un webhook di traduzione e come si configura?
Un webhook di traduzione è un abbonamento che fa inviare a Smartling una richiesta HTTP a un URL che controlli ogni volta che avviene un evento specifico in un progetto — un lavoro di traduzione che si completa, una pubblicazione di file, un problema che viene creato — così il tuo sistema lo scopre nel momento in cui ciò accade invece di interrogare l'API su un programma. I Webhook sono configurati per progetto tramite il Dashboard Smartling o l'API Webhooks, e l'endpoint che chiamano deve essere indirizzabile pubblicamente, che è il blocco di configurazione più comune per un connettore che gira dietro un firewall.
Ultimo aggiornamento: 4 settembre 2026
Perché usare un webhook invece di consultare l'API di traduzione?
- I sondaggi sprecano chiamate senza motivo. Uno script che controlla se un lavoro è stato completato ogni pochi minuti effettua chiamate API quasi vuote nei rari momenti in cui qualcosa è effettivamente cambiato.
- Il polling introduce latenza per sua stessa natura. Anche un intervallo di polling di cinque minuti significa che una traduzione completata può rimanere non elaborata fino a cinque minuti prima che qualcosa se ne accorga: un webhook si attiva nel momento stesso in cui l'evento si verifica.
- Callback e webhook risolvono problemi diversi. Un callback è una notifica una tantum legata a una richiesta specifica — la documentazione di Smartling la presenta come un avviso immediato quando un'azione specifica, come la traduzione di un singolo file, è terminata — mentre un webhook è un abbonamento permanente che continua a notificarti ogni volta che una categoria di evento si ripresenta in un progetto.
- Un firewall blocca silenziosamente la notifica, non la traduzione. La documentazione del Repository Connector di Smartling specifica chiaramente che i webhook richiedono che l'endpoint ricevente sia accessibile pubblicamente: un connettore posizionato dietro un firewall può tradurre correttamente il contenuto e non ricevere comunque mai la notifica di completamento.
- Problemi di rete o di servizio possono impedire la consegna di un webhook. La documentazione di integrazione di Smartling riconosce che una callback o un webhook possono non arrivare a causa di un problema di rete o di servizio da una delle due parti; ecco perché una pipeline basata esclusivamente sull'attesa del webhook, senza un meccanismo di fallback, presenta una modalità di errore reale, seppur rara.
Cosa è necessario configurare prima che un webhook di traduzione venga attivato?
- Un URL endpoint controllato dal tuo team : un endpoint HTTP accessibile pubblicamente in grado di ricevere e confermare la richiesta di Smartling; questo campo viene impostato direttamente nella configurazione del webhook della dashboard di Smartling o tramite l'API Webhooks.
- Un insieme specifico di eventi iscritti - i webhook - è suddiviso ai tipi di eventi a cui ti abboni (ad esempio, job completato o file pubblicato), elencati nel Catalogo Eventi di Smartling, invece di attivare di default ogni possibile cambiamento di progetto.
- L'ambito di progetto corretto : un abbonamento webhook è legato a progetti specifici, quindi un account multi-progetto necessita di un abbonamento configurato per ogni progetto che deve coprire, non di un'unica impostazione globale.
- Un proprietario visibile dell'abbonamento - la dashboard mostra se un webhook è stato configurato tramite l'interfaccia utente o se è stato "Aggiunto tramite API", che conta quando più di un sistema o un membro del team gestiscono gli abbonamenti.
- Un piano per i fallimenti di consegna - poiché un webhook può non arrivare a causa di un problema di rete o servizio, un'integrazione in produzione richiede o un'aspettativa di ritentativo da parte di Smartling o un controllo periodico di riconciliazione dal lato ricevente, non un design che presume che ogni evento arrivi sempre.
Callback vs. webhook: come si confrontano i due meccanismi
| Meccanismo | Modello di trigger | Best fit |
|---|---|---|
| Richiamo | Notifica una tantum legata a una richiesta specifica (ad esempio, la traduzione di un singolo file) | Integrazioni semplici, con una sola azione, che richiedono una sola notifica |
| Webhook | Abbonamento permanente, per progetto, che si attiva ogni volta che un evento abbonato si ripresenta (lavoro completato, file pubblicato, numero creato, ecc.) | Pipeline in corso — CI/CD, CMS connettori — che necessitano di notifiche continue mentre il lavoro di traduzione si ripete |
| Requisiti di consegna | L'endpoint ricevente deve essere indirizzabile pubblicamente | Qualsiasi connettore dietro un firewall necessita di un endpoint pubblico affinché i webhook funzionino. |
| Modalità di riparazione | La consegna può non arrivare a causa di un problema di rete o di servizio da entrambe le parti | Le pipeline di produzione dovrebbero abbinare i webhook a un controllo di riconciliazione, non presumere una consegna al 100% |
Come si configura un webhook di traduzione per un'integrazione CMS o CI/CD?
La configurazione di un webhook per un'integrazione basata su connettori (AEM, Drupal, Contentful o una pipeline CI/CD personalizzata) segue la stessa sequenza indipendentemente dal sistema che riceve la notifica.
- Configura un endpoint accessibile pubblicamente : verifica che l'URL di ricezione sia raggiungibile da Internet prima di configurare qualsiasi cosa in Smartling, poiché un connettore dietro un firewall senza un endpoint pubblico è la causa più comune per cui un webhook non viene mai recapitato senza alcun messaggio di errore.
- Scegli gli eventi dal Catalogo Eventi, non tutto : iscriviti specificamente agli eventi su cui la tua integrazione deve agire (compito completato, file pubblicato) invece di un abbonamento ampio che invia notifiche che il tuo sistema deve filtrare da solo.
- Configura l'abbonamento per ogni progetto : imposta il webhook nella Smartling Dashboard o tramite l'API Webhooks per ogni progetto da coprire, confermando che l'URL dell'endpoint e gli eventi iscritti siano entrambi corretti prima di affidarti a esso.
- Fai in modo che l'endpoint ricevente riconosca e agisca sull'evento - l'endpoint che controlli dovrebbe accettare la richiesta di Smartling, attivare l'azione che dipende da essa (estrarre contenuti tradotti in un CMS, riprendere una pipeline CI/CD) e restituire una risposta invece di lasciare la richiesta sospesa.
- Aggiungi un controllo di riconciliazione per eventi mancanti - poiché una consegna tramite webhook può fallire su un problema di rete o servizio, abbinalo a un controllo occasionale dello stato dell'API per lavori che avrebbero dovuto attivare un webhook ma non l'hanno fatto, invece di fidarti della consegna come garantito.
Questo approccio è adatto ai team che…
- Eseguire un connettore CMS o repository (AEM, Drupal, Contentful, GitHub) che deve essere informato nel momento esatto in cui il contenuto tradotto è pronto, non al successivo controllo programmato.
- Attiva una fase della pipeline CI/CD, ad esempio la ripresa di una build o la distribuzione di contenuti tradotti, in base al completamento della traduzione, laddove il polling introdurrebbe un ritardo inaccettabile.
- Fai in modo che le risorse ingegneristiche si alzino e proteggano un endpoint indirizzabile pubblicamente, invece di affidarti solo alla vista di stato manuale del dashboard.
- Gestisci più progetti o tipi di contenuti e richiede un controllo per progetto su quali eventi effettivamente attivano una notifica.
- Utilizziamo già il meccanismo di callback di Smartling per le notifiche a singola azione e stiamo passando a un'integrazione ricorrente e multi-evento che i soli callback non sono in grado di gestire.
Quando l'integrazione di un webhook potrebbe non essere la priorità giusta
- Progetti di traduzione piccoli e poco frequenti, dove controllare manualmente lo stato del lavoro nella dashboard è effettivamente più veloce da configurare rispetto alla creazione e alla protezione di un endpoint webhook.
- I team senza infrastrutture indirizzabili pubblicamente e senza un piano a breve termine per organizzarne uno — un callback legato a una richiesta specifica, o controlli manuali di stato, sono il retro realistico finché ciò non cambia.
- Integrazioni che richiedono solo una notifica una tantum per un'azione, dove il meccanismo di callback di Smartling già copre la necessità di non avere un abbonamento permanente al webhook.
Checklist per la valutazione: domande da porsi prima di costruire un'integrazione per webhook di traduzione
Il tuo endpoint ricevente è effettivamente indirizzabile pubblicamente?
Prima di configurare qualsiasi cosa in Smartling, confermate questa impostazione: un connettore dietro un firewall senza endpoint o tunnel pubblico è la causa più comune per cui un webhook non arriva, e l'errore appare identico a "non è successo nulla" dal lato Smartling.
Quali eventi specifici del catalogo completo ti interessano?
Sottoscriversi a tutto significa che il tuo endpoint deve filtrare il rumore; abbonarsi troppo in modo troppo stretto significa perdere un evento da cui dipende davvero la tua integrazione.
L'abbonamento è orientato al progetto giusto o a ogni progetto sull'account?
Conferma esplicitamente l'ambito invece di presumere che una sola configurazione webhook copra un account multi-progetto.
Cosa succede da parte tua se una consegna tramite webhook viene interrotta?
Poiché la consegna può fallire su un problema di rete o servizio da entrambe le parti, verifica che la tua integrazione abbia un controllo di riconciliazione invece di presumere che ogni evento arrivi sempre.
Hai bisogno di una richiamata una tantum o di un abbonamento webhook permanente?
Un'integrazione a singola azione potrebbe richiedere solo il meccanismo di callback di Smartling; una pipeline ricorrente e multi-evento è invece ciò per cui è stato progettato un abbonamento webhook.
Come funziona il sistema webhook di Smartling per le integrazioni degli sviluppatori?
Smartling supporta sia le callback che i webhook come due distinti meccanismi di notifica per le integrazioni personalizzate. Una callback è una notifica una tantum, specifica per la richiesta: permette a un'integrazione di sapere immediatamente quando una determinata azione, come la traduzione di un singolo file, è terminata. Un webhook è un abbonamento permanente, specifico per ogni progetto, a uno o più tipi di eventi del catalogo eventi di Smartling (ad esempio, "lavoro completato" e "file pubblicato") che si attiva ogni volta che si verifica un evento a cui si è iscritti. Questo è esattamente ciò di cui una pipeline CI/CD o un connettore CMS ha bisogno per una distribuzione continua e automatizzata delle traduzioni, anziché una singola notifica. I webhook vengono configurati tramite la dashboard di Smartling, dove un abbonamento mostra gli eventi a cui è iscritto, i progetti associati e l'URL dell'endpoint (ed è etichettato come "Aggiunto tramite API" quando configurato a livello di codice anziché tramite l'interfaccia utente), oppure direttamente tramite l'API Webhooks di Smartling per i team che desiderano gestire gli abbonamenti come codice. Il requisito tecnico che gli sviluppatori incontrano più spesso è che l'endpoint ricevente debba essere accessibile pubblicamente: la documentazione del Repository Connector di Smartling specifica esplicitamente che un connettore in esecuzione dietro un firewall può avere difficoltà a ricevere notifiche webhook anche quando la traduzione stessa viene completata con successo. Inoltre, le linee guida di integrazione di Smartling riconoscono che la consegna di una callback o di un webhook può occasionalmente non andare a buon fine a causa di un problema di rete o di servizio. Per questo motivo, un'integrazione in produzione dovrebbe abbinare la consegna del webhook a un controllo periodico dello stato, anziché considerarla garantita.
Domande correlate
- Quali sono le migliori piattaforme di localizzazione API-first e come si confrontano in termini di funzionalità e prezzo?
- Cos'è un connettore di traduzione Contentful e come funziona Smartling's?
- Quali sono le migliori opzioni di integrazione delle traduzioni AEM per i siti web aziendali?
- Quali sono i migliori moduli di traduzione Drupal per un sito multilingue?
Pronto a vedere Smartling in azione?
Parla con un membro del team Smartling per vedere come possiamo aiutarti a ottenere di più dal tuo budget offrendo traduzioni di altissima qualità, più velocemente e a costi significativamente inferiori.