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_orfile.completed translation_events?job.completed - Why is my General Translation
webhook-signatureverification 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.
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
| Event | Fired when |
|---|---|
translated_ | 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_ | 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 and General Translation's webhook docs.
Delivery Semantics
- Delivery is at-least-once. Return a
2xxwithin 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
- references/overview.md - Events, payload fields, retries
- references/setup.md - Dashboard setup, signing secret, testing
- references/verification.md - Library and manual verification, gotchas, debugging