# General Translation Platform: Webhooks
URL: https://generaltranslation.com/es/docs/platform/orgs/webhooks.mdx
---
title: Webhooks
description: Recibe notificaciones en tiempo real cuando se produzcan eventos en tu organización
---

Los webhooks permiten que tu aplicación reciba peticiones HTTP POST cuando se producen eventos en tu organización, como la finalización de un archivo traducido o de un trabajo de traducción.

Los webhooks están disponibles en el **plan Team** y en planes superiores.

## Configuración de un webhook

1. Ve a **Organization Settings → Webhooks**
2. Haz clic en **Create Webhook**
3. Introduce la URL del endpoint donde quieres recibir los eventos (debe ser HTTPS)
4. Selecciona los tipos de eventos a los que quieres suscribirte
5. Haz clic en **Create**

Después de crear el endpoint, ve a la página de detalles del webhook y copia el secreto de firma. Usarás este secreto para verificar que las solicitudes entrantes provienen de General Translation.

Puedes crear hasta **5 endpoints de webhook** por organización.

## Tipos de eventos

| Evento                      | Descripción                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------- |
| `translated_file.completed` | Se activa cuando un archivo traducido finaliza y está listo para descargar                    |
| `translated_file.edited`    | Se activa cuando un usuario edita manualmente un archivo traducido en el editor de traducción |
| `translation_job.completed` | Se activa cuando finaliza un trabajo de traducción                                            |

Cada endpoint puede suscribirse a uno o varios tipos de eventos. Puedes actualizar tus suscripciones en cualquier momento desde la página de detalles del webhook.

## Formato del payload

Cada entrega de webhook es una solicitud HTTP POST con un cuerpo 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"
    }
  }
}
```

El `id` de nivel superior es un identificador de evento estable que puedes usar para deduplicar las entregas en tu sistema.

## Verificación de firmas

Cada solicitud de webhook incluye tres cabeceras para verificar la firma:

| Cabecera            | Description                                                       |
| ------------------- | ----------------------------------------------------------------- |
| `webhook-id`        | El ID del evento (`evt_xxx`)                                      |
| `webhook-timestamp` | Marca temporal Unix (en segundos) en la que se envió la solicitud |
| `webhook-signature` | Firma `v1,<base64-hmac>`                                          |

La firma sigue la convención de [Standard Webhooks](https://www.standardwebhooks.com/). Para verificarla:

1. Concatena: `{webhook-id}.{webhook-timestamp}.{raw request body}`
2. Calcula el HMAC-SHA256 con tu secreto de firma (decodifica el secreto en base64 después de quitar el prefijo `whsec_`)
3. Codifica el resultado en base64 y compáralo con el valor de la firma (después del prefijo `v1,`)
4. Comprueba que la marca temporal esté dentro de los 5 minutos con respecto a la hora actual para evitar ataques de repetición

### Ejemplo (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"];

  // Verificar la vigencia del timestamp (tolerancia de 5 minutos)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error("Timestamp too old");
  }

  // Calcular la firma esperada
  const signingKey = Buffer.from(secret.replace("whsec_", ""), "base64");
  const signedContent = `${msgId}.${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", signingKey)
    .update(signedContent)
    .digest("base64");

  // Comparar (tiempo constante)
  const received = signature.split(",")[1];
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    throw new Error("Invalid signature");
  }

  return JSON.parse(payload);
}
```

También puedes usar la biblioteca [Standard Webhooks](https://www.standardwebhooks.com/) para tu lenguaje de programación, que se encarga de verificar automáticamente.

## Reintentos y entrega

Los webhooks usan **entrega con garantía de al menos una vez**. Si tu endpoint no devuelve una respuesta `2xx` en un plazo de 10 segundos, la entrega se reintenta con retroceso exponencial hasta un máximo de **10 intentos**.

También puedes reintentar manualmente una entrega fallida desde la página de detalles del webhook en el panel.

### Manejo de duplicados

Como la entrega es con garantía de al menos una vez, tu endpoint puede recibir el mismo evento más de una vez. Usa el campo `id` del payload para eliminar duplicados:

```js
app.post("/webhooks/gt", (req, res) => {
  const eventId = req.body.id;

  if (alreadyProcessed(eventId)) {
    return res.status(200).send("OK");
  }

  // Procesar el evento...
  markProcessed(eventId);
  res.status(200).send("OK");
});
```

## Gestionar endpoints

Desde la página de detalles del webhook, puedes:

* **Activar/desactivar** un endpoint sin eliminarlo
* **Actualizar** los tipos de eventos suscritos
* **Ver el historial de entregas** e inspeccionar intentos de entrega individuales
* **Reintentar** una entrega fallida
* **Mostrar** el secreto de firma (para volver a copiarlo)
* **Eliminar** el endpoint

## Buenas prácticas

* **Responde rápido** — devuelve una respuesta `2xx` lo antes posible y, después, procesa el evento de forma asíncrona. Los manejadores de solicitud que tardan demasiado pueden agotar el tiempo de espera.
* **Verifica las firmas** — valida siempre la cabecera `webhook-signature` antes de confiar en el payload.
* **Gestiona duplicados** — almacena los ID de los eventos procesados y omite los duplicados.
* **Usa HTTPS** — los endpoints de webhook deben usar HTTPS en producción.
* **Supervisa los fallos** — revisa periódicamente tu historial de entregas para detectar fallos persistentes que puedan indicar un problema con tu endpoint.

## Permisos

Administrar endpoints de webhook requiere el permiso `org:webhooks:write`. Ver el historial de entregas requiere `org:webhooks:read`. De forma predeterminada, los roles **Owner** y **Admin** tienen ambos permisos. Consulta [Roles y permisos](/docs/platform/orgs/roles) para obtener más detalles.