# General Translation Platform: Webhooks URL: https://generaltranslation.com/fr/docs/platform/orgs/webhooks.mdx --- title: Webhooks description: Recevez des notifications en temps réel lorsque des événements surviennent dans votre organisation --- Les webhooks permettent à votre application de recevoir des requêtes HTTP POST lorsqu’un événement survient dans votre organisation, par exemple lorsqu’un fichier traduit est prêt ou qu’un travail de traduction se termine. Les webhooks sont disponibles avec l’offre **Team** et les offres supérieures. ## Configurer un webhook 1. Accédez à **Paramètres de l’organisation → Webhooks** 2. Cliquez sur **Créer un webhook** 3. Saisissez l’URL de l’endpoint sur lequel vous souhaitez recevoir les événements (doit être en HTTPS) 4. Sélectionnez les types d’événements auxquels vous souhaitez vous abonner 5. Cliquez sur **Créer** Après avoir créé l’endpoint, accédez à la page de détails du webhook et copiez le secret de signature. Vous utiliserez 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 | Événement | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------- | | `translated_file.completed` | Se déclenche lorsqu’un fichier traduit est finalisé et prêt à être téléchargé | | `translated_file.edited` | Se déclenche lorsqu’un fichier traduit est modifié manuellement par un utilisateur dans l’éditeur de traduction | | `translation_job.completed` | Se déclenche lorsqu’un job de traduction est terminé | Chaque endpoint peut s’abonner à un ou plusieurs types d’événements. Vous pouvez mettre à jour vos abonnements à tout moment depuis la page de détails du webhook. ## Format de la payload Chaque livraison de webhook est une requête HTTP POST avec un corps au format 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` à la racine est un identifiant d’événement stable que vous pouvez utiliser pour dédupliquer les livraisons de votre côté. ## Vérification des signatures Chaque requête webhook inclut trois en-têtes pour vérifier la signature : | En-tête | Description | | ------------------- | ---------------------------------------------------------------- | | `webhook-id` | ID de l’événement (`evt_xxx`) | | `webhook-timestamp` | Horodatage Unix (en secondes) au moment de l’envoi de la requête | | `webhook-signature` | Signature `v1,` | La signature suit la convention [Standard Webhooks](https://www.standardwebhooks.com/). Pour la vérifier : 1. Concaténez : `{webhook-id}.{webhook-timestamp}.{corps brut de la requête}` 2. Calculez le HMAC-SHA256 à l’aide de votre secret de signature (décodez le secret en base64 après avoir supprimé le préfixe `whsec_`) 3. Encodez le résultat en base64, puis comparez-le à la valeur de la signature (après le préfixe `v1,`) 4. Vérifiez que l’horodatage se situe à moins de 5 minutes de l’heure actuelle afin d’éviter 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"]; // Vérifier la fraîcheur de l'horodatage (tolérance de 5 minutes) const now = Math.floor(Date.now() / 1000); if (Math.abs(now - parseInt(timestamp)) > 300) { throw new Error("Timestamp too old"); } // Calculer la signature attendue const signingKey = Buffer.from(secret.replace("whsec_", ""), "base64"); const signedContent = `${msgId}.${timestamp}.${payload}`; const expected = crypto .createHmac("sha256", signingKey) .update(signedContent) .digest("base64"); // Comparer (en temps constant) 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/) adaptée à votre langage, qui gère automatiquement la vérification. ## Nouvelles tentatives et livraison Les webhooks utilisent une **livraison au moins une fois**. Si votre endpoint ne renvoie pas de réponse `2xx` dans les 10 secondes, la livraison est retentée avec un délai exponentiel, jusqu'à **10 tentatives**. Vous pouvez également relancer manuellement une livraison ayant échoué depuis la page de détails du webhook dans le tableau de bord. ### Gestion des doublons Comme la livraison suit un modèle « at-least-once », votre endpoint peut recevoir le même événement plusieurs fois. Utilisez le champ `id` du payload pour dédupliquer : ```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 Depuis la page de détail du webhook, vous pouvez : * **Activer/désactiver** un endpoint sans le supprimer * **Mettre à jour** les types d’événements auxquels il est abonné * **Consulter l’historique des livraisons** et examiner chaque tentative de livraison * **Relancer** une livraison ayant échoué * **Afficher** le secret de signature (pour le recopier) * **Supprimer** l’endpoint ## Bonnes pratiques * **Répondez rapidement** — renvoyez une réponse `2xx` aussi vite que possible, puis traitez l’événement de manière asynchrone. Les gestionnaires qui s’exécutent longtemps risquent d’atteindre le délai d’expiration. * **Vérifiez les signatures** — validez toujours l’en-tête `webhook-signature` avant de faire confiance au payload. * **Gérez les doublons** — stockez les ID des événements déjà traités et ignorez les doublons. * **Utilisez HTTPS** — les endpoints de webhook doivent utiliser HTTPS en production. * **Surveillez les échecs** — consultez régulièrement votre historique de livraison pour repérer les échecs persistants pouvant indiquer un problème avec votre endpoint. ## Autorisations La gestion des endpoints de webhook nécessite l’autorisation `org:webhooks:write`. La consultation de l’historique des livraisons nécessite l’autorisation `org:webhooks:read`. Par défaut, les rôles **Owner** et **Admin** disposent de ces deux autorisations. Consultez [Rôles et autorisations](/docs/platform/orgs/roles) pour plus de détails.