# General Translation Webhooks

[General Translation](https://generaltranslation.com) is an AI localization platform. Its webhooks report translated files and translation jobs as signed HTTP POSTs with a JSON body. Signatures follow the Standard Webhooks convention. Webhooks need a Starter or Enterprise plan, and each organization can have up to 5 endpoints.

## When to Use This Skill

* How do I receive General Translation webhooks?
* How do I verify a General Translation webhook signature?
* Where do I find my General Translation webhook signing secret?
* How do I handle `translated_file.completed` or `translation_job.completed` events?
* Why is my General Translation `webhook-signature` verification failing?
* Why are late General Translation retries rejected after 5 minutes?

## Verification (core)

| Header | Value |
| --- | --- |
| `webhook-id` | Event ID (`evt_...`), the same on every retry. Equals `id` in the body |
| `webhook-timestamp` | Unix seconds when the request was sent |
| `webhook-signature` | One or more space-separated `v1,<base64 HMAC-SHA256>` entries |

Signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`. The key is the base64-**decoded** part of the endpoint's secret after `whsec_`. The examples use the `standardwebhooks` library (npm, PyPI), which tries every `v1` entry, ignores other versions such as `v1a`, and compares in constant time.

```javascript
const { Webhook } = require('standardwebhooks');

// rawBody: exact request body string, NOT re-serialised JSON
function verify(rawBody, req, secret = process.env.GENERAL_TRANSLATION_WEBHOOK_SECRET) {
  // Fall back to svix-* names when webhook-id is absent
  const p = req.get('webhook-id') ? 'webhook' : 'svix';
  return new Webhook(secret).verify(rawBody, {
    'webhook-id': req.get(`${p}-id`),
    'webhook-timestamp': req.get(`${p}-timestamp`),
    'webhook-signature': req.get(`${p}-signature`),
  }); // returns the parsed event; throws → respond 401
}

```

Python: `from standardwebhooks.webhooks import Webhook`, then `Webhook(secret).verify(await request.body(), {...same three keys...})`.

> **Timestamp window.** The library always enforces a fixed 5-minute window. Hookdeck retries and replays resend the **original** timestamp, so the library rejects a late retry or replay after 5 minutes. If you receive webhooks through Hookdeck and need to accept those, use the manual verifier in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/general-translation-webhooks/references/verification.md), where the window can be dropped or widened.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/general-translation-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/general-translation-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/general-translation-webhooks/examples/fastapi/).

## Event Envelope

```json
{ "id": "evt_xxx", "object": "event", "type": "translated_file.completed",
  "createdAt": "2026-04-30T12:00:00.000Z", "apiVersion": "2026-03-06.v1",
  "data": { "object": { "object": "translated_file", "id": "trf_xxx", "locale": "fr",
                        "fileFormat": "JSON", "completedAt": "2026-04-30T12:00:00.000Z" } } }

```

`type` is the event. `data.object.object` is the resource kind (`translated_file` or `translation_job`), not the event. `id` is the dedupe key. Resource fields are frozen when the event is created and reused on retries and manual replays.

## Common Event Types

| Event | Fired when |
| --- | --- |
| `translated_file.completed` | A translated file is completed and ready to download |
| `translated_file.edited` | A user manually edits a translated file in the translation editor (`editedAt` instead of `completedAt`) |
| `translation_job.completed` | A translation job completes (resource has only `jobId` and `completedAt`) |

These are the three documented types, and the list may not be exhaustive. Acknowledge unknown types with `200`.

> **Full payloads:** [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/general-translation-webhooks/references/overview.md) and [General Translation's webhook docs](https://generaltranslation.com/en-US/docs/platform/dashboard/reference/webhooks).

## Delivery Semantics

* Delivery is at-least-once. Return a `2xx` within **10 seconds**, enqueue the event and process it asynchronously.
* A non-2xx or a timeout is retried with exponential backoff, up to 10 attempts. You can retry manually from **Organization > Developer > Webhook Events**.
* No ordering is guaranteed. Dedupe on `id`.

## Environment Variables

```bash
GENERAL_TRANSLATION_WEBHOOK_SECRET=whsec_xxxxx   # the full whsec_ value; handlers fail closed (500) without it

```

Get it from **Organization > Developer > Webhooks** → your endpoint's detail page. Each endpoint has its own secret.

## Local Development

```bash
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 general-translation --path /webhooks/general-translation

```

Add the printed URL with **Add endpoint** (it must be HTTPS), choose event types, and complete a translation.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/general-translation-webhooks/references/overview.md) - Events, payload fields, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/general-translation-webhooks/references/setup.md) - Dashboard setup, signing secret, testing
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/general-translation-webhooks/references/verification.md) - Library and manual verification, gotchas, debugging