Polling vs Webhooks

AudioSpliter supports two ways to track job status: polling the API and receiving webhooks. Each approach has trade-offs.

Polling

Polling means repeatedly calling the Get Job endpoint until the status changes.

Polling Example

async function waitForJob(jobId, apiKey, intervalMs = 5000) {
  while (true) {
    const response = await fetch(
      `https://api.audiospliter.com/api/v1/splits/${jobId}`,
      { headers: { 'X-API-Key': apiKey } }
    );
    const job = await response.json();

    if (job.status === 'completed') return job;
    if (job.status === 'failed') throw new Error(job.error?.message);

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }
}

When to Use Polling

• Simple scripts that run once and exit
• CLI tools where you need to wait for results
• Environments without a web server (serverless functions, cron jobs)
• Low volume (a few jobs per day)

Polling Best Practices

• Start with a 5-second interval and increase for longer jobs
• Respect rate limits -- do not poll faster than once per second
• Set a timeout so you do not poll forever
• Use exponential backoff for long-running jobs

Webhooks

Webhooks push status changes to your server in real time.

When to Use Webhooks

• Production applications processing many jobs
• Real-time UIs that need to update when jobs complete
• Workflow automation (trigger downstream actions immediately)
• High volume (more efficient than polling)

Webhook Advantages

Factor	Polling	Webhooks
API calls	Many (per job)	Zero (notification is pushed)
Latency	Depends on interval	Near real-time
Complexity	Lower	Higher (need HTTPS endpoint)
Rate limit impact	Consumes quota	No impact

Recommendation

For most production use cases, webhooks are preferred. They are more efficient, faster, and do not consume your rate limit quota. Use polling for simple scripts, debugging, or environments where you cannot host a webhook endpoint.

Hybrid Approach

You can use both: submit the job with a webhookUrl and also poll as a fallback. If the webhook fires first, stop polling. If polling completes first, ignore the later webhook (deduplicate using X-AudioSpliter-Delivery).