Returning Results
Hop business customers can upload a file with 50,000 long addresses and get 50,000 short links back. That takes about two minutes. Holding a web request open that long invites timeouts, dropped connections and angry retries. The work belongs in a background job — but then how does the answer get back to whoever asked?
The rule
Hand out a ticket now; deliver the answer later.
The first response comes immediately and carries a ticket — a job id or a status address:
POST /imports (the file)
202 Accepted
Location: /jobs/5521202 Accepted means "received, not finished". The finished result is then delivered one of three ways:
- Polling — the client asks
/jobs/5521every few seconds: "queued", "running 40%", "done". Simple and works everywhere; costs some wasted requests. - Callback (webhook) — the client registers an address, and Hop calls it when the job ends. No wasted requests, but the client must run a server that can receive calls, and a lost callback needs a fallback.
- Push — an open connection (such as a WebSocket or server-sent events) lets Hop send progress straight to a browser as it happens.
In every case the result itself — here, a file of 50,000 short links — is stored and fetched from a result address. It does not live inside the original request.
The shortcut
Ask: "Who is waiting, and can they receive a call?" A person in a browser → poll or push. Another company's server → webhook, with polling as the safety net.
Accept
Store the file, create job 5521, reply
202 Acceptedwith/jobs/5521. Under 100 ms.
The trap is a job with no way to report failure. "Done" is not the only ending: jobs need a clear "failed" status with a reason, or clients poll forever.
Drills
Answer fast — trust the rule.
What does an HTTP 202 Accepted response tell the client?
A mobile app with no server of its own wants a job's result. Which approach fits best?
What is the main advantage of a webhook over polling?
A job hits an error halfway. What should the status address report?
Where should the 50,000 new short links live when the job finishes?
Remember
- Hand out a ticket now; deliver the answer later.
- Shortcut: a person waiting → poll or push; a server waiting → webhook plus polling as backup.
- Trap: no "failed" status, and results held inside a long open request.