# General Translation Platform: webhook URL: https://generaltranslation.com/it/docs/platform/dashboard/reference/webhooks.mdx Docs index: https://generaltranslation.com/llms.txt Description: Configura gli endpoint webhook, verifica le firme e gestisci gli eventi di traduzione di General Translation. Riferimento per i webhook. I webhook inviano eventi di traduzione al tuo backend come richieste HTTP POST firmate. Usali per attivare i tuoi workflow quando cambiano file o job. *Nota: i webhook richiedono un piano Team o Enterprise.* ## Creare un webhook [#create-webhook] 1. Vai a **Organization > Developer > webhook**. 2. Fai clic su **Aggiungi endpoint**. 3. Inserisci l'URL dell'endpoint in cui vuoi ricevere gli eventi. L'URL deve utilizzare HTTPS. 4. Seleziona i tipi di evento a cui vuoi iscriverti. 5. Fai clic su **Crea endpoint**. Dopo aver creato l'endpoint, apri la pagina dei dettagli del webhook e copia il segreto di firma. Usa questo segreto per verificare che le richieste in entrata provengano da General Translation. Puoi creare fino a **5 endpoint webhook** per ogni Organization. ## Tipi di evento [#event-types] Ogni endpoint può sottoscrivere uno o più tipi di evento. Puoi aggiornare le sottoscrizioni dalla pagina dei dettagli del webhook. * `translated_file.completed` viene attivato quando un file tradotto è stato completato ed è pronto per il download. * `translated_file.edited` viene attivato quando un file tradotto viene modificato manualmente da un utente nel Translation Editor. * `translation_job.completed` viene attivato quando un translation job viene completato. ## Formato del payload [#payload-format] Ogni consegna di webhook avviene tramite una richiesta HTTP POST con corpo JSON: ```json { "id": "evt_xxx", "type": "translated_file.completed", "created_at": "2026-04-30T12:00:00.000Z", "api_version": "2026-03-06.v1", "data": { "object": { "id": "file_xxx", "org_id": "org_xxx", "project_id": "project_xxx", "branch_id": "branch_xxx", "source_file_id": "src_xxx", "file_id": "file_xxx", "version_id": "ver_xxx", "locale": "fr", "file_format": "json", "data_format": null, "completed_at": "2026-04-30T12:00:00.000Z" } } } ``` L’`id` di primo livello è un identificatore evento stabile che puoi usare per individuare ed eliminare le consegne duplicate. ## Verifica delle firme [#verify-signatures] Ogni richiesta webhook include tre header: * `webhook-id` è l'ID dell'evento, ad esempio `evt_xxx`. * `webhook-timestamp` è il timestamp Unix, in secondi, che indica quando è stata inviata la richiesta. * `webhook-signature` è la firma `v1,`. La firma segue la convenzione di [Standard Webhooks](https://www.standardwebhooks.com/). Per verificare una richiesta: 1. Concatena `{webhook-id}.{webhook-timestamp}.{raw request body}`. 2. Decodifica il secret in Base64 dopo aver rimosso il prefisso `whsec_`, così da ottenere la chiave di firma. 3. Calcola l'HMAC-SHA256 sulla stringa concatenata usando la chiave di firma decodificata. 4. Codifica il risultato in Base64. 5. Confrontalo con il valore della firma dopo il prefisso `v1,`. 6. Verifica che il timestamp rientri in un intervallo di 5 minuti rispetto all'ora corrente, per prevenire attacchi di replay. ### Esempio: Node.js ```js import crypto from "crypto"; function verifyWebhook(payload, headers, secret) { const msgId = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; const signature = headers["webhook-signature"]; const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(timestamp)) > 300) { throw new Error("Timestamp too old"); } const signingKey = Buffer.from(secret.replace("whsec_", ""), "base64"); const signedContent = `${msgId}.${timestamp}.${payload}`; const expected = crypto .createHmac("sha256", signingKey) .update(signedContent) .digest("base64"); const received = signature.split(",")[1]; if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) { throw new Error("Invalid signature"); } return JSON.parse(payload); } ``` Puoi anche usare la libreria [Standard Webhooks](https://www.standardwebhooks.com/) per il tuo linguaggio di programmazione, che gestisce automaticamente la verifica. ## Gestisci i tentativi e la consegna [#handle-retries-delivery] I webhook usano **at-least-once consegna**. Se il tuo endpoint non restituisce una risposta `2xx` entro 10 secondi, la consegna viene ritentata con backoff esponenziale fino a **10 tentativi**. Puoi ritentare manualmente una consegna non riuscita da **Organization > Developer > Eventi webhook** nella Dashboard. Seleziona l'evento nell'elenco, quindi passa il cursore su una riga in **Tentativi di consegna** e fai clic su **Riprova**. Espandi un tentativo non riuscito per esaminare il campo **Errore**. In caso di risposta non `2xx`, l'errore include lo stato HTTP e può includere un estratto del body della risposta dell'endpoint opportunamente ripulito. General Translation legge fino a 4.096 byte dalla risposta e memorizza al massimo 500 caratteri a fini diagnostici. ## Visualizzare gli eventi e i tentativi di consegna [#view-events] 1. Vai a **Organization > Developer > Evento webhook**. 2. Seleziona un evento dall'elenco degli eventi attivati nella tua Organization. 3. Esamina i **tentativi di consegna** per quell'evento. Ogni tentativo mostra lo stato, l'URL dell'endpoint e un timestamp. Espandi un tentativo con un esito registrato per vedere se era **Automatico** o **Manuale**, la relativa latenza di andata e ritorno e un riepilogo dell'**Errore** in caso di errori di trasporto, come errori di connessione o timeout. I tentativi in attesa senza un esito registrato non possono essere espansi. I tentativi automatici vengono visualizzati come consegne **Automatiche**. I tentativi avviati dal Dashboard vengono visualizzati come **Manuali**. ## Gestire eventi duplicati [#handle-duplicate-events] Poiché la consegna è di tipo at-least-once, il tuo endpoint potrebbe ricevere lo stesso evento più di una volta. Usa il campo `id` nel payload per eliminare i duplicati. ```js app.post("/webhooks/gt", (req, res) => { const eventId = req.body.id; if (alreadyProcessed(eventId)) { return res.status(200).send("OK"); } // Elabora l'evento... markProcessed(eventId); res.status(200).send("OK"); }); ``` ## Gestire gli endpoint [#manage-endpoints] Da **Organization > Developer > webhook**, puoi: * Abilitare o disabilitare un endpoint senza eliminarlo * Aggiornare i tipi di evento a cui è iscritto * Visualizzare il segreto di firma * Eliminare l'endpoint Da **Organization > Developer > Eventi webhook**, puoi visualizzare la cronologia delle consegne, esaminare i singoli tentativi di consegna e ritentare una consegna fallita. ## Buone pratiche [#best-practices] * Rispondi rapidamente con una risposta `2xx`, quindi elabora l'evento in modo asincrono. * Verifica l'header `webhook-signature` prima di considerare attendibile il payload. * Memorizza gli ID degli eventi già elaborati e ignora i duplicati. * Usa HTTPS per gli endpoint webhook in produzione. * Monitora **Webhooks > Events** per individuare eventuali errori persistenti nelle consegne. ## Autorizzazioni [#permissions] La gestione degli endpoint webhook e il ritentativo delle consegne richiedono l'autorizzazione `org:webhooks:write`. Per visualizzare gli eventi e i tentativi di consegna è richiesta l'autorizzazione `org:webhooks:read`. Per impostazione predefinita, i ruoli **Admin** e **Developer** dispongono di entrambe le autorizzazioni. (Per maggiori dettagli, vedi [ruoli e autorizzazioni](/docs/platform/dashboard/reference/roles-and-permissions)). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.