# General Translation Platform: Webhooks
URL: https://generaltranslation.com/es/docs/platform/dashboard/reference/webhooks.mdx
---

title: Webhooks
description: Configura endpoints de webhook, verifica firmas y gestiona eventos de traducción de General Translation.

---

Los webhooks envían eventos de traducción a tu backend mediante solicitudes HTTP POST firmadas. Úsalos para activar tus propios flujos de trabajo cuando cambien archivos o trabajos.

## Crear un webhook [#create-webhook]

1. Ve a **Organization Settings > Webhooks**.
2. Haz clic en **Crear webhook**.
3. Introduce la URL del endpoint en el que quieres recibir eventos. La URL debe usar HTTPS.
4. Selecciona los tipos de eventos a los que quieres suscribirte.
5. Haz clic en **Crear**.

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

Puedes crear hasta **5 endpoints de webhook** por Organization.

## Tipos de eventos [#event-types]

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

* `translated_file.completed` se activa cuando un archivo traducido se completa y queda listo para descargarse.
* `translated_file.edited` se activa cuando un usuario edita manualmente un archivo traducido en el Translation Editor.
* `translation_job.completed` se activa cuando finaliza un trabajo de traducción.

## Formato del payload [#payload-format]

Cada entrega de webhook se realiza mediante 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 eliminar entregas duplicadas.

## Verificar firmas [#verify-signatures]

Cada solicitud de webhook incluye tres cabeceras:

* `webhook-id` es el ID del evento, por ejemplo `evt_xxx`.
* `webhook-timestamp` es la marca de tiempo Unix, en segundos, en la que se envió la solicitud.
* `webhook-signature` es la firma `v1,<base64-hmac>`.

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

Para verificar una solicitud:

1. Concatena `{webhook-id}.{webhook-timestamp}.{raw request body}`.
2. Decodifica el secreto en Base64 después de quitar el prefijo `whsec_` para obtener la clave de firma.
3. Calcula el HMAC-SHA256 de la cadena concatenada usando la clave de firma decodificada.
4. Codifica el resultado en Base64.
5. Compáralo con el valor de la firma después del prefijo `v1,`.
6. Comprueba que la marca de tiempo 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"];

  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);
}
```

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.

## Gestiona los reintentos y la entrega [#handle-retries-delivery]

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 vuelve a intentar con backoff exponencial hasta un máximo de **10 intentos**.

Puedes volver a intentar manualmente una entrega fallida desde la página de detalles del webhook en el panel de control.

## Gestiona eventos duplicados [#handle-duplicate-events]

Como la entrega se realiza al menos una vez, tu endpoint puede recibir el mismo evento más de una vez. Usa el campo `id` del payload para deduplicarlos.

```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 [#manage-endpoints]

Desde la página de webhooks, puedes:

* Habilitar o deshabilitar un endpoint sin eliminarlo
* Actualizar los tipos de eventos a los que está suscrito
* Ver el historial de entregas
* Inspeccionar intentos de entrega individuales
* Reintentar una entrega fallida
* Mostrar el secreto de firma
* Eliminar el endpoint

## Buenas prácticas [#best-practices]

* Responde rápido con una respuesta `2xx` y luego procesa el evento de forma asíncrona.
* Verifica la cabecera `webhook-signature` antes de confiar en el payload.
* Almacena los IDs de los eventos ya procesados y omite los duplicados.
* Usa HTTPS para los endpoints de webhook en producción.
* Supervisa el historial de entregas para detectar fallos persistentes.

## Permisos [#permissions]

Para gestionar endpoints de webhook, se requiere el permiso `org:webhooks:write`.

Para ver el historial de entregas, se requiere `org:webhooks:read`.

De forma predeterminada, el rol **Admin** tiene ambos permisos. Consulta [roles y permisos](/docs/platform/dashboard/reference/roles-and-permissions) para más detalles.