# General Translation Platform: Webhooks URL: https://generaltranslation.com/fr/docs/platform/dashboard/reference/webhooks.mdx --- title: Webhooks description: Configurez les endpoints de webhook, vérifiez les signatures et traitez les événements de traduction de General Translation. --- Les webhooks envoient des événements de traduction à votre backend sous forme de requêtes HTTP POST signées. Utilisez-les pour déclencher vos propres workflows lorsque des fichiers ou des jobs sont modifiés. ## Créer un webhook [#create-webhook] 1. Accédez à **Paramètres de l’organisation > Webhooks**. 2. Cliquez sur **Create Webhook**. 3. Saisissez l’URL de l’endpoint sur lequel vous souhaitez recevoir les événements. L’URL doit utiliser HTTPS. 4. Sélectionnez les types d’événements auxquels vous souhaitez vous abonner. 5. Cliquez sur **Create**. Après avoir créé l’endpoint, ouvrez la page de détail du webhook et copiez le secret de signature. Utilisez ce secret pour vérifier que les requêtes entrantes proviennent bien de General Translation. Vous pouvez créer jusqu’à **5 endpoints de webhook** par organisation. ## Types d’événements [#event-types] Chaque endpoint peut s’abonner à un ou plusieurs types d’événements. Vous pouvez mettre à jour les abonnements depuis la page de détail du webhook. * `translated_file.completed` est émis lorsqu’un fichier traduit est finalisé et prêt à être téléchargé. * `translated_file.edited` est émis lorsqu’un fichier traduit est modifié manuellement par un utilisateur dans le Translation Editor. * `translation_job.completed` est émis lorsqu’un job de traduction se termine. ## Format du payload [#payload-format] Chaque livraison de webhook consiste en une requête HTTP POST avec un corps 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` de niveau supérieur est un identifiant d’événement stable que vous pouvez utiliser pour dédupliquer les envois. ## Vérifier les signatures [#verify-signatures] Chaque requête de webhook inclut trois en-têtes : * `webhook-id` est l’ID de l’événement, par exemple `evt_xxx`. * `webhook-timestamp` est l’horodatage Unix, en secondes, correspondant au moment où la requête a été envoyée. * `webhook-signature` est la signature `v1,`. La signature suit la convention [Standard Webhooks](https://www.standardwebhooks.com/). Pour vérifier une requête : 1. Concaténez `{webhook-id}.{webhook-timestamp}.{corps brut de la requête}`. 2. Décodez en Base64 le secret après avoir supprimé le préfixe `whsec_` afin d’obtenir la clé de signature. 3. Calculez le HMAC-SHA256 de la chaîne concaténée à l’aide de la clé de signature décodée. 4. Encodez le résultat en Base64. 5. Comparez-le à la valeur de la signature après le préfixe `v1,`. 6. Vérifiez que l’horodatage est à moins de 5 minutes de l’heure actuelle afin d’empêcher les attaques par rejeu. ### Exemple : 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); } ``` Vous pouvez également utiliser la bibliothèque [Standard Webhooks](https://www.standardwebhooks.com/) pour votre langage de programmation, qui gère automatiquement la vérification. ## Gérer les tentatives et la livraison [#handle-retries-delivery] Les webhooks utilisent une **garantie de livraison « at-least-once »**. Si votre endpoint ne renvoie pas de réponse `2xx` dans les 10 secondes, la livraison est retentée avec une temporisation exponentielle, dans la limite de **10 tentatives**. Vous pouvez relancer manuellement une livraison en échec depuis la page de détail du webhook dans le Dashboard. ## Gérer les événements en double [#handle-duplicate-events] Comme la livraison est effectuée au moins une fois, votre endpoint peut recevoir le même événement plusieurs fois. Utilisez le champ `id` du payload pour supprimer les doublons. ```js app.post("/webhooks/gt", (req, res) => { const eventId = req.body.id; if (alreadyProcessed(eventId)) { return res.status(200).send("OK"); } // Traiter l'événement... markProcessed(eventId); res.status(200).send("OK"); }); ``` ## Gérer les endpoints [#manage-endpoints] Depuis la page du webhook, vous pouvez : * Activer ou désactiver un endpoint sans le supprimer * Mettre à jour les types d’événements auxquels il est abonné * Consulter l’historique des livraisons * Examiner les tentatives de livraison individuelles * Relancer une livraison ayant échoué * Afficher le secret de signature * Supprimer l’endpoint ## Bonnes pratiques [#best-practices] * Répondez rapidement avec un code de réponse `2xx`, puis traitez l’événement de manière asynchrone. * Vérifiez l’en-tête `webhook-signature` avant de vous fier au payload. * Stockez les ID des événements traités et ignorez les doublons. * Utilisez HTTPS pour les endpoints de webhook de production. * Surveillez l’historique des livraisons pour repérer les échecs persistants. ## Permissions [#permissions] La gestion des endpoints de webhook nécessite la permission `org:webhooks:write`. La consultation de l’historique des livraisons nécessite `org:webhooks:read`. Par défaut, le rôle **Admin** dispose de ces deux permissions. Consultez [les rôles et permissions](/docs/platform/dashboard/reference/roles-and-permissions) pour en savoir plus.