Set up an endpoint
- Open the signed-in Developers page. Webhooks can only be managed there, not with an API key.
- Add an https address on your server and pick the events it should get. You can add up to 5 endpoints.
- Copy the signing secret (
whsec_...). It is shown once. Store it like a password. - Press Send test. SoundHalo sends a
webhook.testevent at once and shows how your server answered.
Addresses must use https and a public domain name. IP addresses, localhost, internal names and addresses that redirect are refused. To test on your own computer, use a tunnel service that gives you a public https address.
Events
| Event | When | data.object |
|---|---|---|
dub.awaiting_confirmation | A dub has its quote and waits for you to confirm. Also sent again if a dub needs a new amount. | dub |
job.completed | A dub succeeded, or a queued job (such as async transcription) succeeded. | dub or job |
job.failed | A dub failed, or a queued job failed or was cancelled. | dub or job |
balance.topped_up | A balance top-up was paid and added. | balance |
webhook.test | You pressed Send test. Only sent to that endpoint. | none |
Requests that answer right away (sync calls) send no webhook.
Payloads
Every event is a JSON POST with the same outer shape:
{
"id": "evt_...",
"type": "dub.awaiting_confirmation",
"created_at": "2026-11-16T01:57:07.373Z",
"data": { ... }
} Dub events
data is { "object": "dub", "dub": { ... } }, where dub has exactly the shape of GET /v1/dubbing/:id: status, quote, lines, output and warnings. See the dubbing guide for a full example.
Job events
A job event carries the job's status but not its result or token. Read the result with GET /v1/jobs/:id and the job token you kept.
{
"id": "evt_...",
"type": "job.completed",
"created_at": "2026-11-16T02:03:08.920Z",
"data": {
"object": "job",
"job": {
"job_id": "job_7dbceef5aca5b6b27848e719a18a8f69",
"operation": "extract.transcribe",
"status": "succeeded",
"created_at": "2026-11-16T02:02:58.484Z",
"updated_at": "2026-11-16T02:03:08.920Z",
"warnings": [],
"output_asset_ids": []
}
}
} Balance events
{
"id": "evt_...",
"type": "balance.topped_up",
"created_at": "...",
"data": { "object": "balance", "pack": "credits_20", "amount_micros": 20000000 }
} pack is the top-up's id: credits_20 for $20 or credits_50 for $50. amount_micros is the amount added in micro-dollars (20,000,000 = $20).
Test events
data is { "message": "This is a test event from SoundHalo." }.
An event larger than 64 KB (for example a dub with a very long script) is sent with data set to { "truncated": true }. Read the full dub with GET /v1/dubbing/:id.
Verify the signature
Signing follows Standard Webhooks, an open format many services use. Each request has three headers:
webhook-id | The event id (evt_...). The same on every retry of the event. |
|---|---|
webhook-timestamp | When this attempt was sent, in Unix seconds. |
webhook-signature | v1, followed by a base64 HMAC-SHA256 signature. |
To check a request:
- Take the secret, remove the
whsec_prefix and base64-decode the rest. Those bytes are the key. - Build the text
<webhook-id>.<webhook-timestamp>.<raw body>. Use the body exactly as received, before any JSON parsing. - Compute HMAC-SHA256 of that text with the key and base64-encode it.
- Compare it with the value after
v1,using a constant-time comparison (one that takes the same time whether or not the values match, so attackers cannot guess it piece by piece). - Refuse timestamps more than 5 minutes from your clock. This stops replays: someone who copies a real request cannot send it again later.
- Remember each
webhook-idyou handled and skip repeats. Retries reuse it.
The official standardwebhooks libraries (npm, pip) also work: pass them the whole whsec_... secret, the raw body and the headers. They check the signature and the 5-minute window, but you still need to skip repeated ids yourself.
Node.js example
A complete receiver with no dependencies:
// Receives SoundHalo webhooks with Node.js built-ins only (Node 18 or later).
// Run: SOUNDHALO_WEBHOOK_SECRET=whsec_... node webhook.mjs
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';
const secret = process.env.SOUNDHALO_WEBHOOK_SECRET; // "whsec_..." from the Developers page
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const TOLERANCE_SEC = 5 * 60;
const seen = new Set(); // use your database in production, so restarts keep it
function verify(headers, rawBody) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures) return false;
// Refuse old or future timestamps, so a copied request cannot be replayed later.
const sentAt = Number(timestamp);
if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > TOLERANCE_SEC) return false;
// Sign "<webhook-id>.<webhook-timestamp>.<raw body>" with the secret's bytes.
const expected = createHmac('sha256', key)
.update(`${id}.${timestamp}.`)
.update(rawBody)
.digest();
// The header can hold several space-separated signatures, each "v1,<base64>".
return signatures.split(' ').some(entry => {
const [version, value] = entry.split(',');
if (version !== 'v1' || !value) return false;
const given = Buffer.from(value, 'base64');
return given.length === expected.length && timingSafeEqual(given, expected);
});
}
createServer((req, res) => {
if (req.method !== 'POST') { res.writeHead(405).end(); return; }
const chunks = [];
req.on('data', chunk => chunks.push(chunk));
req.on('end', () => {
const rawBody = Buffer.concat(chunks); // verify the exact bytes, before JSON.parse
if (!verify(req.headers, rawBody)) { res.writeHead(400).end('invalid signature'); return; }
// Answer within 10 seconds. Do slow work after replying.
res.writeHead(200).end('ok');
// Retries send the same webhook-id. Handle each id once.
const id = req.headers['webhook-id'];
if (seen.has(id)) return;
seen.add(id);
const event = JSON.parse(rawBody.toString('utf8'));
if (event.type === 'dub.awaiting_confirmation') {
const { dub } = event.data;
console.log('Quote ready', dub.dub_id, dub.quote.balance_micros, 'micro-dollars');
} else if (event.type === 'job.completed' || event.type === 'job.failed') {
console.log(event.type, event.data.object, event.data[event.data.object]);
} else {
console.log(event.type, event.data);
}
});
}).listen(3000); Delivery and retries
- Any 2xx answer within 10 seconds counts as delivered. Anything else, a timeout or a redirect counts as a failure.
- A failed delivery is tried again 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours after each failure: 8 attempts in all, over about 45 hours. Then it is marked failed.
- Test events are sent once, with no retries.
- Events can arrive out of order, especially after retries. Use
created_at, or read the current state withGET /v1/dubbing/:idorGET /v1/jobs/:id. - The Developers page shows a delivery log of recent deliveries: event, status, attempts, your server's answer and the next try.
- Deleting an endpoint stops its pending deliveries.
Checklist
- Verify every signature against the raw body.
- Refuse timestamps older than 5 minutes.
- Skip
webhook-ids you already handled. - Answer 2xx quickly, then do the work.
- Do not confirm a dub automatically from a webhook unless the amount is within a limit the account owner set.