# General Translation Platform: webhook URL: https://generaltranslation.com/it/docs/platform/dashboard/reference/webhooks.mdx --- title: webhook description: Configura gli endpoint webhook, verifica le firme e gestisci gli eventi di traduzione di General Translation. --- 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. ## Creare un webhook [#create-webhook] 1. Vai a **Impostazioni dell'organizzazione > Webhook**. 2. Fai clic su **Crea webhook**. 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**. 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 organizzazione. ## 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 dalla pagina dei dettagli del webhook nella Dashboard. ## 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] Dalla pagina del webhook, puoi: * Abilitare o disabilitare un endpoint senza eliminarlo * Aggiornare i tipi di evento a cui è iscritto * Visualizzare la cronologia delle consegne * Esaminare i singoli tentativi di consegna * Ritentare una consegna fallita * Visualizzare il segreto di firma * Eliminare l'endpoint ## 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 la cronologia delle consegne per individuare eventuali errori persistenti. ## Autorizzazioni [#permissions] La gestione degli endpoint webhook richiede l'autorizzazione `org:webhooks:write`. Per visualizzare la cronologia delle consegne è richiesta l'autorizzazione `org:webhooks:read`. Per impostazione predefinita, il ruolo **Admin** dispone di entrambe le autorizzazioni. Per maggiori dettagli, vedi [ruoli e autorizzazioni](/docs/platform/dashboard/reference/roles-and-permissions).