# General Translation Platform: Webhook URL: https://generaltranslation.com/it/docs/platform/orgs/webhooks.mdx --- title: Webhook description: Ricevi notifiche in tempo reale quando si verificano eventi nella tua organizzazione --- I webhook consentono alla tua applicazione di ricevere richieste HTTP POST quando si verificano eventi nella tua organizzazione, ad esempio quando viene completata la traduzione di un file o termina un job di traduzione. I webhook sono disponibili a partire dal **piano Team**. ## Configurare un webhook 1. Vai a **Organization Settings → Webhooks** 2. Fai clic su **Create Webhook** 3. Inserisci l'URL dell'endpoint a cui vuoi ricevere gli eventi (deve essere HTTPS) 4. Seleziona i tipi di evento a cui vuoi iscriverti 5. Fai clic su **Create** Dopo aver creato l'endpoint, vai alla pagina dei dettagli del webhook e copia il segreto di firma. Userai questo segreto per verificare che le richieste in arrivo provengano da General Translation. Puoi creare fino a **5 endpoint di webhook** per organizzazione. ## Tipi di evento | Evento | Descrizione | | --------------------------- | --------------------------------------------------------------------------------------------------------- | | `translated_file.completed` | Si attiva quando un file tradotto viene completato ed è pronto per il download | | `translated_file.edited` | Si attiva quando un file tradotto viene modificato manualmente da un utente nell'editor di traduzione | | `translation_job.completed` | Si attiva quando un job di traduzione viene completato | Ogni endpoint può sottoscrivere uno o più tipi di evento. Puoi aggiornare le tue sottoscrizioni in qualsiasi momento dalla pagina dei dettagli del webhook. ## Formato del payload Ogni invio del webhook è una richiesta HTTP POST con un 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 eliminare i duplicati delle consegne nel tuo sistema. ## Verifica delle firme Ogni richiesta webhook include tre header per la verifica della firma: | Header | Descrizione | | ------------------- | ---------------------------------------------------------- | | `webhook-id` | ID dell'evento (`evt_xxx`) | | `webhook-timestamp` | Timestamp Unix (in secondi) dell'invio della richiesta | | `webhook-signature` | Firma `v1,` | La firma segue la convenzione di [Standard Webhooks](https://www.standardwebhooks.com/). Per verificarla: 1. Concatena: `{webhook-id}.{webhook-timestamp}.{raw request body}` 2. Calcola l'HMAC-SHA256 usando il tuo segreto di firma (decodifica il segreto da base64 dopo aver rimosso il prefisso `whsec_`) 3. Codifica il risultato in base64 e confrontalo con il valore della firma (dopo il prefisso `v1,`) 4. Verifica che il timestamp rientri in una finestra 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"]; // Verifica la validità del timestamp (tolleranza di 5 minuti) const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(timestamp)) > 300) { throw new Error("Timestamp too old"); } // Calcola la firma attesa const signingKey = Buffer.from(secret.replace("whsec_", ""), "base64"); const signedContent = `${msgId}.${timestamp}.${payload}`; const expected = crypto .createHmac("sha256", signingKey) .update(signedContent) .digest("base64"); // Confronta (tempo costante) 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. ## Nuovi tentativi e consegna I webhook usano una modalità di consegna **at-least-once**. Se il tuo endpoint non restituisce una risposta `2xx` entro 10 secondi, la consegna viene ritentata con backoff esponenziale fino a un massimo di **10 tentativi**. Puoi anche ritentare manualmente una consegna non riuscita dalla pagina dei dettagli del webhook nella dashboard. ### Gestione dei duplicati Poiché la consegna segue una semantica at-least-once, il tuo endpoint potrebbe ricevere lo stesso evento più di una volta. Usa il campo `id` nel payload per rimuovere 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"); }); ``` ## Gestione degli endpoint Dalla pagina dei dettagli del webhook, puoi: * **Abilitare/disabilitare** un endpoint senza eliminarlo * **Aggiornare** i tipi di evento sottoscritti * **Visualizzare la cronologia delle consegne** e ispezionare i singoli tentativi di consegna * **Riprovare** una consegna non riuscita * **Mostrare** il segreto di firma (per copiarlo nuovamente) * **Eliminare** l'endpoint ## Buone pratiche * **Rispondi rapidamente** — restituisci una risposta `2xx` il più rapidamente possibile, quindi elabora l'evento in modo asincrono. Gli handler di lunga durata rischiano di andare in timeout. * **Verifica le firme** — valida sempre l'header `webhook-signature` prima di considerare attendibile il payload. * **Gestisci i duplicati** — memorizza gli ID degli eventi già elaborati e ignora i duplicati. * **Usa HTTPS** — in produzione, gli endpoint webhook devono usare HTTPS. * **Monitora gli errori** — controlla periodicamente la cronologia delle consegne per individuare errori persistenti che potrebbero indicare un problema con il tuo endpoint. ## Permessi La gestione degli endpoint webhook richiede l'autorizzazione `org:webhooks:write`. Per visualizzare la cronologia delle consegne è richiesta `org:webhooks:read`. Per impostazione predefinita, i ruoli **Owner** e **Admin** dispongono di entrambe le autorizzazioni. Per maggiori dettagli, vedi [Ruoli e permessi](/docs/platform/orgs/roles).