# General Translation Platform: Webhooks URL: https://generaltranslation.com/fr/docs/platform/dashboard/reference/webhooks.mdx Docs index: https://generaltranslation.com/llms.txt Description: Configurez les endpoints de webhook, vérifiez les signatures et traitez les événements de traduction de General Translation. Référence des webhooks. 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. *Remarque : les webhooks nécessitent un plan Team ou Enterprise.* ## Créer un webhook [#create-webhook] 1. Accédez à **Organization > Developer > Webhooks**. 2. Cliquez sur **Add endpoint**. 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 endpoint**. 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 **Organization > Developer > Webhook Events** dans le Dashboard. Sélectionnez l’événement dans la liste, puis survolez une ligne sous **Tentatives de livraison** et cliquez sur **Réessayer**. Développez une tentative en échec pour examiner son champ **erreur**. Pour une réponse non-`2xx`, l'erreur inclut le code d'état HTTP et peut inclure un extrait nettoyé du body de la réponse de l'endpoint. General Translation lit jusqu'à 4 096 octets de la réponse et n'en stocke pas plus de 500 caractères à des fins de diagnostic. ## Afficher les événements et les tentatives de livraison [#view-events] 1. Accédez à **Organization > Developer > Webhook Events**. 2. Sélectionnez un événement dans la liste des événements déclenchés au sein de votre Organization. 3. Consultez les **tentatives de livraison** associées à cet événement. Chaque tentative affiche un état, l’URL de l’endpoint et un horodatage. Développez une tentative dont le résultat a été enregistré pour voir si elle était **Automatique** ou **Manuelle**, sa latence aller-retour et un résumé de l’**Erreur** en cas d’échec de transport, tel qu’une erreur de connexion ou un délai d’expiration. Les tentatives en attente dont le résultat n’a pas été enregistré ne peuvent pas être développées. Les nouvelles tentatives automatiques apparaissent comme des livraisons **Automatiques**. Les nouvelles tentatives lancées depuis le dashboard apparaissent comme **Manuelles**. ## 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 **Organization > Developer > Webhooks**, vous pouvez : * Activer ou désactiver un endpoint sans le supprimer * Mettre à jour les types d’événements auxquels il est abonné * Afficher le secret de signature * Supprimer l’endpoint Depuis **Organization > Developer > Webhook Events**, vous pouvez consulter l’historique des livraisons, examiner les tentatives de livraison individuelles et relancer une livraison ayant échoué. ## 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 **Webhooks > Événements** pour repérer les échecs de livraison persistants. ## Permissions [#permissions] La gestion des endpoints de webhook et la relance des livraisons nécessitent la permission `org:webhooks:write`. La consultation des événements et des tentatives de livraison nécessite `org:webhooks:read`. Par défaut, les rôles **Admin** et **Developer** disposent de ces deux permissions. (Consultez [les rôles et permissions](/docs/platform/dashboard/reference/roles-and-permissions) pour en savoir plus). ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.