Guide to General Translation Webhooks: Features and Best Practices
General Translation localises apps and content with AI. You push source files, it translates them into your target locales, and translators can refine the results in its editor. Its webhooks tell your backend when that work lands: a translated file is ready, someone edits a translation by hand, or a whole translation job finishes. Teams use them to pull translations into a repository or CDN, open a pull request, or kick off a deploy once every locale is done.
What are General Translation webhooks?
Webhooks are an organisation-level feature on the Starter and Enterprise plans. You add up to five endpoints in the dashboard and subscribe each to one or more event types. General Translation then sends each event as a signed HTTPS POST with a JSON body.
The signature follows the Standard Webhooks convention, with webhook-id, webhook-timestamp and webhook-signature headers and a whsec_ secret per endpoint. The event body is versioned with an apiVersion field, and its resource fields are captured when the event is created, so a retry or a manual replay sends exactly what the first attempt sent.
General Translation webhook features
| Feature | Details |
|---|---|
| Plans | Starter or Enterprise |
| Configuration | Organisation > Developer > Webhooks, up to 5 endpoints |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | webhook-signature, with webhook-id and webhook-timestamp |
| Secret | Per endpoint, whsec_..., on the endpoint's detail page |
| Body | JSON, camelCase fields, apiVersion included |
| Event routing | Body field type |
| Response window | 2xx within 10 seconds |
| Retries | Exponential backoff, up to 10 attempts. Manual retry from Webhook Events |
| Delivery | At least once. No ordering guarantee documented |
| Source IPs | Not published |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
translated_ | A translated file is completed and ready to download | Pull the file into your repo or CDN, open a pull request |
translated_file.edited | A user manually edits a translated file in the translation editor | Re-sync the edited file, notify reviewers |
translation_ | A translation job completes | Mark a release as localized, start a deploy |
Every event has the same envelope. Here is General Translation's translated_ example, with its placeholder IDs:
{
"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",
"orgId": "org_xxx",
"projectId": "project_xxx",
"branchId": "branch_xxx",
"sourceFileId": "src_xxx",
"fileId": "file_xxx",
"versionId": "ver_xxx",
"locale": "fr",
"fileFormat": "JSON",
"dataFormat": null,
"completedAt": "2026-04-30T12:00:00.000Z"
}
}
}
The top-level id equals the webhook-id header and identifies the event across retries. object is always event; the resource kind is data.object.object. translated_file.edited has the same resource fields with editedAt in place of completedAt. translation_ is much smaller: its resource holds only jobId and completedAt.
Setting up General Translation webhooks
- In the dashboard, go to Organisation > Developer > Webhooks and click Add endpoint.
- Enter an HTTPS endpoint URL and select the event types. You can change the subscription later from the endpoint's detail page.
- Click Create endpoint, open the detail page, and copy the signing secret into
GT_WEBHOOK_SECRET. Keep thewhsec_prefix in the stored value.
Each endpoint has its own secret, so a staging endpoint's secret won't verify production deliveries. You can disable an endpoint without deleting it.
To put Hookdeck in the path, create a source with the General Translation type, paste the secret, and use the source URL as the endpoint. Forward it to a local server during development with the Hookdeck CLI:
npx hookdeck-cli listen 3000 general-translation --path /webhooks/general-translation
Securing General Translation webhooks
General Translation's verification steps are the standard ones: remove whsec_, base64-decode the rest as the key, concatenate <webhook-id>.<webhook-timestamp>.<raw body>, compute HMAC-SHA256, and compare with the value after v1,. Its Node sample compares only the first entry in the header. The function below accepts a match on any v1, entry, as the format allows:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The docs also tell you to check that the timestamp is within five minutes of the current time. For a direct receiver that's a reasonable replay guard. Behind Hookdeck it would reject legitimate late deliveries, because Hookdeck applies no timestamp tolerance and keeps the original webhook-timestamp when it retries or replays an event.
This receiver stores the event and lets a worker download the translated file:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
// syncQueue.push(job) records the job and resolves once it is stored.
function createGeneralTranslationReceiver(syncQueue) {
const app = express();
app.post('/webhooks/general-translation', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.GT_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const body = parseJsonObject(req.body);
if (!body) return res.sendStatus(400); // signed, but not a JSON object
const { id, type, data } = body;
const resource = data && data.object;
if (!resource || typeof resource !== 'object') return res.sendStatus(400);
try {
await syncQueue.push({ eventId: id, type, locale: resource.locale, fileId: resource.fileId });
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
If General Translation posts to a Hookdeck source and the signature doesn't match, Hookdeck still answers 200. The request is marked as failed verification and goes no further.
Make General Translation webhooks production-ready. Hookdeck Event Gateway verifies every translation event and lets you route each locale's files to the pipeline that publishes them.
General Translation webhook limitations and pain points
Ten attempts, then manual retries
The Problem: Translation events from an outage stop arriving and need someone to resend them.
Why It Happens: A failed delivery is retried with exponential backoff for up to 10 attempts. After that, the only way to resend is to select the event under Webhook Events and click Retry on a delivery attempt.
Workarounds:
- Check Webhook Events after an outage. Failed attempts show the HTTP status and up to 500 characters of your response body.
- Reconcile translation status through the API before a release.
How Hookdeck Can Help: Hookdeck takes each event on the first attempt and stores it, then retries delivery to your service on your schedule, without anyone clicking through the dashboard.
Frozen payloads
The Problem: A replayed translated_ points at a version that is no longer current.
Why It Happens: Resource fields are captured when the event is created and reused for every retry and replay, even if the file has changed since.
Workarounds:
- Use
versionIdandfileIdfrom the event, then fetch the latest version from the API if you need the current state. - Treat
translated_file.editedevents as newer data than the completed event for the same file.
How Hookdeck Can Help: Hookdeck's event history records when each delivery arrived, which helps you see which version reached your pipeline.
Only five endpoints
The Problem: Separate endpoints for each environment and service run out quickly.
Why It Happens: An organisation can have at most five endpoints.
Workarounds:
- Use one endpoint per environment and route internally by
typeorprojectId.
How Hookdeck Can Help: A single Hookdeck source can fan out to many destinations, with filters on type or data.object.projectId, so one General Translation endpoint serves several services.
Best practices
Deduplicate on id
Delivery is at least once. Store the evt_ ID before syncing anything. This idempotency guide explains why and how.
Pin your parser to apiVersion
Each body names its apiVersion. Log it, and alert when a new value appears so a format change doesn't surprise your sync job.
Deploy on job completion, sync on file completion
translated_ fires per file and locale. translation_ tells you the whole job is done, which is the better trigger for a build or release.
Answer within 10 seconds
Downloading and committing files takes longer than ten seconds. Store the event, return 2xx, and do the work in a worker.
Conclusion
General Translation's three events arrive in a versioned envelope with frozen resource fields. The limits to remember are the five-endpoint cap and the manual step after ten failed attempts.
Hookdeck Event Gateway lets one General Translation endpoint feed several pipelines and keeps events safe during outages. Create your free account.