Core concepts

Webhooks

Receive a signed HTTPS request when a job finishes, and verify that it came from Voiser.

Instead of polling, pass a webhook_url when you create a job. When the job reaches a final status, Voiser sends a POST request with the job to that URL.

curl -X POST https://api.34.181.188.80.sslip.io/v2/text-to-speech \
  -H "Authorization: Bearer $VOISER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your order has shipped.",
    "voice_id": "voice_8f2Kq1LmZx3T",
    "webhook_url": "https://example.com/webhooks/voiser"
  }'

The URL must be a public https address; private and local network addresses are refused with 400 validation_webhook_url.

The event

POST /webhooks/voiser HTTP/1.1
Content-Type: application/json
User-Agent: Voiser-Webhooks/1.0
Voiser-Event-Id: evt_5c8e2b7f1d9a4e6b8c3f0a2d4e6b8c1f
Voiser-Signature: t=1763375074,v1=6f1c2b…e94a
{
  "id": "evt_5c8e2b7f1d9a4e6b8c3f0a2d4e6b8c1f",
  "object": "event",
  "type": "job.succeeded",
  "created_at": "2026-11-17T10:24:34.950Z",
  "data": {
    "job": {
      "id": "0193a5b2-7c41-7d2e-9f3a-6b8c1d2e4f50",
      "object": "job",
      "operation": "text_to_speech",
      "status": "succeeded",
      "progress": 100,
      "credits": { "estimated": 120, "charged": 96 },
      "result": { "file_id": "0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30", "duration_ms": 4350, "characters": 61 },
      "files": [{ "id": "0193a5b3-1d0e-7a51-8c44-2f9b6e7d1a30", "role": "output", "index": 0 }],
      "error": null,
      "created_at": "2026-11-17T10:24:31.000Z",
      "started_at": "2026-11-17T10:24:31.420Z",
      "completed_at": "2026-11-17T10:24:34.910Z"
    }
  }
}
Event typeSent when
job.succeededThe job finished and its outputs are ready.
job.failedThe job failed; data.job.error explains why.
job.canceledThe job was canceled.

data.job is the same job object that GET /v2/jobs/{id} returns. The event does not contain download URLs: call GET /v2/files/{id} when you need the file.

Responding

  • Answer with any 2xx status within 10 seconds. Do the real work (downloading, processing) after you respond, for example in a background queue.
  • Redirects are not followed; a 3xx counts as a failure.
  • If the delivery fails (non-2xx, timeout, network error), Voiser retries up to 6 times with increasing delays.
Handle duplicates

Retries mean the same event can reach you more than once. Voiser-Event-Id (and the body's id) stays the same across retries of one event, so store processed event ids and answer 200 to repeats. A job finishes only once, so data.job.id works as a key too.

Verifying signatures

Every v2 webhook is signed with your API key's webhook signing secret, shown in the studio next to the key under Settings → API keys. Always verify the signature before trusting the body.

The Voiser-Signature header has the form t=<unix seconds>,v1=<hex signature>. To verify it:

  1. Split the header on , and read t (timestamp) and v1 (signature).
  2. Build the signed payload: the timestamp, a dot, and the raw request body exactly as received: "<t>.<raw body>".
  3. Compute an HMAC-SHA256 of that payload with your signing secret and hex-encode it.
  4. Compare it with v1 using a constant-time comparison.
  5. Reject the request if t is more than 5 minutes away from your clock, to block replays.

Use the raw bytes of the body. Parsing the JSON and serialising it again changes whitespace and breaks the signature.

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.VOISER_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300;

export function verifyVoiserSignature(rawBody, header, secret = SECRET) {
  const parts = Object.fromEntries((header ?? "").split(",").map((p) => p.trim().split("=", 2)));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// Keep the raw body: the signature covers the exact bytes.
app.post("/webhooks/voiser", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyVoiserSignature(raw, req.get("Voiser-Signature"))) return res.status(400).send("bad signature");

  const event = JSON.parse(raw);
  res.sendStatus(200); // answer fast, then process
  if (event.type === "job.succeeded") {
    // queue work for event.data.job (idempotently, by event.data.job.id)
  }
});

app.listen(3000);

Testing locally

Your endpoint must be reachable from the internet. During development, expose your local server with a tunnelling tool and use the public https URL it gives you as webhook_url. Log the raw body and headers of the first deliveries to check your verification code.

v1 webhooks

The legacy v1 API keeps its original webhook format: the body has the v1 result shape and is not signed. If you rely on v1 webhooks, plan a move to v2 to get signatures. See Migrating from v1.