Suno API webhooks, done right

Music generation takes 1–3 minutes, so you have two ways to find out a job finished: poll GET /api/jobs/{id} on a loop, or pass a callback_url and let the API push you a webhook the moment it’s done. Webhooks are cheaper and lower-latency — but only if you verify them. Here’s how to do it properly.

The signature scheme

Tunova signs every webhook. Two headers come with the POST:

X-Webhook-Timestamp — unix seconds when we sent it.
X-Webhook-Signature — sha256=<hex>, the HMAC-SHA256 of <timestamp>.<raw-body> keyed with your whsec_… secret (view/rotate it on the dashboard’s API-keys page).

Two rules that trip people up: (1) verify against the raw request body, before any JSON parsing re-serializes it; (2) use a constant-time comparison so you don’t leak timing information.

Verify it — Node

import { createHmac, timingSafeEqual } from "node:crypto"; function verify({ secret, timestamp, body, signature, toleranceSec = 300 }) { if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSec) return false; const expected = createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex"); const provided = signature.startsWith("sha256=") ? signature.slice(7) : signature; const a = Buffer.from(expected), b = Buffer.from(provided); return a.length === b.length && timingSafeEqual(a, b); } // Express: capture the RAW body so the signature matches byte-for-byte app.post("/hooks/tunova", express.raw({ type: "*/*" }), (req, res) => { const ok = verify({ secret: process.env.TUNOVA_WEBHOOK_SECRET, timestamp: req.header("X-Webhook-Timestamp"), body: req.body.toString("utf8"), signature: req.header("X-Webhook-Signature"), }); if (!ok) return res.sendStatus(401); res.sendStatus(200); // ack fast, then process the job });

Verify it — Python

import hmac, hashlib, time def verify(secret: str, timestamp: str, body: str, signature: str, tolerance=300) -> bool: # reject stale deliveries (replay protection) if abs(time.time() - int(timestamp)) > tolerance: return False expected = hmac.new(secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest() provided = signature[7:] if signature.startswith("sha256=") else signature return hmac.compare_digest(expected, provided) # Flask: verify against the RAW body BEFORE parsing JSON raw = request.get_data(as_text=True) if not verify(WHSEC, request.headers["X-Webhook-Timestamp"], raw, request.headers["X-Webhook-Signature"]): abort(401)

Timestamp tolerance (replay protection)

Reject deliveries whose timestamp is more than a few minutes old (300s above). That stops an attacker from replaying a captured valid webhook later.

Idempotency & retries

We retry delivery on non-2xx, so your handler must be idempotent: key on the job_id and ignore a repeat you’ve already processed. Ack fast (return 200 immediately), then do the slow work — audio download, DB writes — out of band, so a slow handler doesn’t look like a failure and trigger a retry.

Don’t want to write this?

The Tunova SDKs ship the verifier above as verifyWebhook (Node) / Tunova.verify_webhook (Python) — one call. And because Tunova is billed only on success, a status: "failed" webhook means the tokens already refunded themselves; your handler just logs it. See the quickstart to get a key (50 free tokens, no card).

Tunova is an independent service, not affiliated with or endorsed by Suno.