Developer API

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

EventSent when
audio.job.completedAn audio job finished.
audio.job.failedAn audio job failed.
uploader.job.completedAt least one file was uploaded.
uploader.job.failedEvery file failed.
spoofer.job.completedAt least one asset was fetched.
spoofer.job.failedNo 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.

Code
{
  "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",
    "...": "..."
  }
}
HeaderValue
X-JG-EventThe event name.
X-JG-Signaturet=<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.

Node.js
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;
}
PHP
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 2xx status 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 id to ignore duplicates.

Keeping your system in sync

  1. Create a record on your side first, then send its ID as external_id.

  2. Store the returned job_id on that record.

  3. When the webhook arrives, find the record by external_id and save the result.

  4. As a safety net, poll GET for 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.