Developer API
Webhooks and syncing
Receive job results on your own URL, verify that they really come from JualGame, and keep your records in sync.
Setup
Set your webhook URL on the Developer API page in the JualGame portal. A signing secret starting with whsec_ is created the first time you save a URL. The URL must use https and be reachable from the public internet.
Events
| Event | Sent when |
audio.job.completed | An audio job finished. |
audio.job.failed | An audio job failed. |
uploader.job.completed | At least one file was uploaded. |
uploader.job.failed | Every file failed. |
spoofer.job.completed | At least one asset was fetched. |
spoofer.job.failed | No asset could be fetched. |
Payload
The body is JSON. data has exactly the shape of the GET response for that job, including your external_id.
{
"id": "evt_3f9a1c0b7d2e4a6f8b1c2d3e",
"event": "audio.job.completed",
"created_at": "2026-10-04T13:02:19.000Z",
"data": {
"job_id": "cmutty9s10001oi2j696p2kgb",
"external_id": "order-123",
"status": "completed",
"...": "..."
}
}| Header | Value |
X-JG-Event | The event name. |
X-JG-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
Verify the signature
Compute an HMAC-SHA256 of <t>.<raw body> with your signing secret and compare it to v1. Use the raw request body exactly as received, before any JSON parsing. Reject requests whose timestamp is more than 5 minutes old.
const crypto = require('crypto');
function isFromJualGame(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(signatureHeader.split(',').map((x) => x.split('=')));
const expected = crypto.createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
const same = expected.length === String(parts.v1).length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(String(parts.v1)));
return fresh && same;
}function isFromJualGame(string $rawBody, string $signatureHeader, string $secret): bool {
parse_str(str_replace(',', '&', $signatureHeader), $parts);
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
$fresh = abs(time() - (int) $parts['t']) < 300;
return $fresh && hash_equals($expected, $parts['v1'] ?? '');
}Delivery and retries
Answer with any
2xxstatus within 10 seconds. Do slow work after you have answered.A failed delivery is retried after 5 seconds, 30 seconds and 2 minutes: four attempts in total.
Redirects are not followed, and URLs that resolve to private or local addresses are refused.
The same event can arrive more than once. Use
idto ignore duplicates.
Keeping your system in sync
Create a record on your side first, then send its ID as
external_id.Store the returned
job_idon that record.When the webhook arrives, find the record by
external_idand save the result.As a safety net, poll
GETfor any job still processing on your side after a few minutes. Webhooks can be lost if your server was down for all four attempts.
Result files are temporary: 2 hours for audio, 1 hour for spoofer. Download them to your own storage when the webhook arrives.
