Developer docs

Webhooks

SoundHalo can call your server when a job finishes, a dub is ready to confirm or your balance is topped up. Every request is signed, so you can check it really came from SoundHalo.

Set up an endpoint

  1. Open the signed-in Developers page. Webhooks can only be managed there, not with an API key.
  2. Add an https address on your server and pick the events it should get. You can add up to 5 endpoints.
  3. Copy the signing secret (whsec_...). It is shown once. Store it like a password.
  4. Press Send test. SoundHalo sends a webhook.test event 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

EventWhendata.object
dub.awaiting_confirmationA dub has its quote and waits for you to confirm. Also sent again if a dub needs a new amount.dub
job.completedA dub succeeded, or a queued job (such as async transcription) succeeded.dub or job
job.failedA dub failed, or a queued job failed or was cancelled.dub or job
balance.topped_upA balance top-up was paid and added.balance
webhook.testYou 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:

event
{
  "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.

job.completed
{
  "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

balance.topped_up
{
  "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-idThe event id (evt_...). The same on every retry of the event.
webhook-timestampWhen this attempt was sent, in Unix seconds.
webhook-signaturev1, followed by a base64 HMAC-SHA256 signature.

To check a request:

  1. Take the secret, remove the whsec_ prefix and base64-decode the rest. Those bytes are the key.
  2. Build the text <webhook-id>.<webhook-timestamp>.<raw body>. Use the body exactly as received, before any JSON parsing.
  3. Compute HMAC-SHA256 of that text with the key and base64-encode it.
  4. 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).
  5. Refuse timestamps more than 5 minutes from your clock. This stops replays: someone who copies a real request cannot send it again later.
  6. Remember each webhook-id you 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:

webhook.mjs
// 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 with GET /v1/dubbing/:id or GET /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.