Webhooks vs Polling for Long-Running Image Jobs

Polling is the simpler choice for most image APIs: you start a job, then ask for its status until it finishes. Webhooks are better when you run many slow jobs and want the server to tell you when each one is done. The right pick depends on your volume, your hosting and whether a shopper is waiting on screen.

This guide is for developers building on a virtual try-on API or any image service where a render can take longer than one request.

Why do image APIs need an async pattern at all?

Generating or editing an image can take longer than a normal web request. A browser, load balancer or serverless function may give up before it finishes.

So many APIs split the work in two: one call to start the job, and a second step to get the result. How you do that second step is the choice between polling and webhooks.

How does polling work?

With polling, your code asks the API about a job over and over until it returns a result.

1. Send the job. The API replies that it is still running and gives you a job ID or a status URL.
2. Wait a short interval.
3. Request the status.
4. If it is not done, go back to step 2. If it is done, read the image.

ZeDaq.ai's try-on endpoint works this way when a render takes time. Per the API reference, POST /api/v1/tryon can return 200 with the image, or 202 with a job_id and a poll_url. On a 202, call the poll URL every 2 seconds until it returns 200 with the image. The docs do not mention webhooks.

How do webhooks work?

With a webhook, you give the API a URL on your server. When the job ends, the API sends a request to that URL with the result or a link to it.

You then need a public endpoint that:

• accepts the request quickly and replies with a success code,
• checks that the call really came from the API,
• matches the result to the right shopper or order,
• handles the same event arriving twice.

Your server stores the result, and your front end learns about it through a page refresh, a push channel or its own polling.

When is polling the better choice?

Polling suits most storefront cases:

• A shopper is waiting. The browser or your backend can check status while a loading state shows.
• You have no public endpoint. Static sites and some hosts cannot receive inbound requests.
• Volume is low or moderate. A few jobs at a time do not make polling costly.
• You want fewer moving parts. There is nothing to verify or retry on your side.

Its downside is wasted requests. If jobs usually finish quickly, most polls return "not yet".

When are webhooks the better choice?

Webhooks pay off in different situations:

• Many jobs run at once, such as batch processing a catalog.
• Jobs are slow, so polling spends many requests waiting.
• No one is watching. A background job needs no live status screen.
• You already run a backend that can receive and verify callbacks.

The cost is more code and more failure modes. If your endpoint is down, you may miss an event unless the API retries.

How do the two compare side by side?

Question	Polling	Webhooks
Setup effort	Low	Higher
Needs a public URL	No	Yes
Latency to the result	Up to one interval	Near immediate
Wasted requests	Yes	No
Security work	API key only	Verify each callback
Risk of a missed result	Low	Present if the endpoint fails

How do you poll without causing problems?

Good polling is polite polling. Follow the API's own advice on the interval, and never poll in a tight loop.

• Use the documented interval. If the docs give one, use it.
• Set a maximum wait. After a limit you choose, stop and show an error or a retry button.
• Stop when the shopper leaves. Cancel timers when the page or modal closes.
• Back off on errors. On rate-limit responses, wait longer before the next call. The guide to rate limits and quotas in image APIs covers this.
• Handle failures cleanly. A job can end in an error, so check the status before you read the image.

Also prepare the input. Smaller, correctly cropped photos finish sooner, as covered in image preprocessing before a try-on API call.

What does a simple polling loop look like?

Here is a minimal pattern in JavaScript. It starts a job, checks the status URL on a fixed interval, and gives up after a maximum wait that you choose. The endpoint and field names follow the ZeDaq.ai API reference.

async function runTryOn(body, apiKey) {
  const start = await fetch(`${BASE_URL}/api/v1/tryon`, {
    method: "POST",
    headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const first = await start.json();
  if (start.status === 200) return first;

  const deadline = Date.now() + MAX_WAIT_MS;
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 2000));
    const res = await fetch(first.poll_url, { headers: { "x-api-key": apiKey } });
    if (res.status === 200) return res.json();
  }
  throw new Error("Render took too long");
}

Treat this as a sketch. Check the API reference for the base URL (set as BASE_URL above) and the full response format, and do not ship an API key in public browser code.

What happens when something fails halfway?

Both patterns need a plan for failure. Ask these questions for each one:

• What if the job fails? Polling shows a failed status you can read. A webhook should carry the failure too, so you do not wait forever.
• What if the shopper clicks twice? Without care, you start two jobs and may pay for both. Disable the button while a job runs.
• What if your server restarts? With polling, keep the job ID somewhere that survives a restart. With webhooks, make sure you can handle a late event for a job you no longer track.
• What if the same event arrives twice? Webhook senders often retry. Store the job ID and ignore a result you have already saved.

Writing these answers down before you build saves debugging later.

How should you think about cost?

Cost has two parts: what the API charges and what your own system spends.

On the API side, check how your provider bills a job. For ZeDaq.ai, the API reference says usage is charged only when a render succeeds, so polling does not add charges.

On your side, polling adds a small amount of traffic per job. Webhooks add an endpoint to host, secure and monitor. For a store with a few shoppers using try-on at a time, either cost is small. At catalog scale, the extra requests from polling may start to matter, and webhooks become more attractive.

What is a quick decision guide?

Use this short list:

1. Is a shopper waiting on the page? Start with polling.
2. Can your host receive inbound requests? If not, polling is your only option.
3. Do you process batches in the background? Consider webhooks.
4. Do you need results the second they are ready? Consider webhooks, plus a page poll as a backup.
5. Is your team small? Choose the simpler pattern and revisit later.

Can you combine both?

Yes. A common design uses webhooks on the server for reliability and a short poll on the page for the shopper's screen. If the webhook is late, the page poll still shows the result. Add this only if you have the volume to justify it.

Which should you pick for a fashion store?

For a product page where one shopper uploads one photo, start with polling. It needs no public endpoint and matches how the shopper experiences the wait. Move to webhooks if you add batch jobs or see polling costs grow.

Whichever you pick, tie the result back to the size advice you give. A try-on image and a size suggestion work best together, as shown in AI size recommendation for fashion stores.

FAQs

What is a good polling interval?

Use the interval your API documents. For ZeDaq.ai, the API reference says to poll every 2 seconds.

Do webhooks guarantee delivery?

No. Delivery depends on your endpoint being up and on the provider's retry policy. Design for missed or repeated events.

Does polling cost more than webhooks?

It can cost more requests, but check how your provider bills. For ZeDaq.ai, usage is charged only when a render succeeds, and polling to completion counts as one usage.

Can I poll from the browser?

Be careful with API keys in browser code. Use a key locked to your domain, or poll through your own backend.