Suno API webhooks: what actually works
A webhook is the right shape for a multi-minute render, but the supported integration path today is polling. Here is how to make polling event-driven inside your own system.
Is there a callback URL?
The standard path is submit → query → download; there is no callback URL to register in the normal integration. If a provider promises webhooks, ask for the exact event shape, signature, retry policy and replay window before you design around it.
Do not build your queue on an undocumented callback that may disappear in the next release.
Make polling behave like an event
Persist the task id, poll every 3–5 seconds, and emit one internal event when the task reaches a terminal state. Deduplicate by task id so a retry or a duplicate poll cannot enqueue the same song twice.
This gives your application the same shape as a webhook without depending on an external callback.
Failure semantics
- failed / error: terminal; read the reason and do not keep polling.
- timeout: not terminal; query the same task before doing anything else.
- retry: reads are idempotent; writes must not be retried until the task state is known.
Next: task lifecycle · rate limits · Python example.
常见问题 / FAQ
Can I register a callback URL?
On the standard integration path, no. Use polling and emit your own internal event when the task completes.
How often should I poll?
Every 3–5 seconds. Faster polling does not finish the render sooner and spends rate limit.
What if my worker restarts?
Persist the task id in your database. On restart, resume polling that id instead of submitting a new generation.
注册只需要邮箱，一次生成 0.6 元出 2 首，MP3 与 WAV 下载不限次。