Agent skill

General Translation Webhooks Skill

Receive and verify General Translation (generaltranslation.com) AI localization webhooks, signed with Standard Webhooks. Use when setting up a General Translation webhook endpoint, getting the whsec_ signing secret, debugging webhook-id / webhook-timestamp / webhook-signature verification, or handling translated_file.completed, translated_file.edited and translation_job.completed events.

Install this skill

npx skills add hookdeck/webhook-skills --skill general-translation-webhooks


General Translation 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)

HeaderValue
webhook-idEvent ID (evt_...), the same on every retry. Equals id in the body
webhook-timestampUnix seconds when the request was sent
webhook-signatureOne 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.

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, where the window can be dropped or widened.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Envelope

{ "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

EventFired when
translated_file.completedA translated file is completed and ready to download
translated_file.editedA user manually edits a translated file in the translation editor (editedAt instead of completedAt)
translation_job.completedA 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 and General Translation's webhook docs.

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

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

# 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →