TL;DR: If an operation can outlive a normal HTTP timeout, do not make the caller hold a connection open. Return 202 Accepted with a pointer to a status resource, let clients poll it with a server-supplied Retry-After, and add webhooks as an optimisation for clients that can receive them. Polling is the reliable baseline; callbacks are the efficient layer on top. Most production APIs need both, and the hard part is not the happy path but retries, duplicates, expiry and failure reporting.
Why long-running operations break naive APIs
A synchronous POST /reports that generates a report, provisions a tenant or reconciles a ledger works fine in development, where the work takes two seconds. In production it meets load balancers with idle timeouts, mobile clients on flaky networks, serverless platforms with hard execution limits and client libraries that retry on timeout. The retry is the dangerous part: the first request may still be running when the second arrives, and now you have two reports, two tenants or two payments.
Moving the work off the request path solves the timeout but creates a new contract problem. The client sent a request and got... what, exactly? How does it learn the outcome? How long can it wait? What if it asks twice? Three families of answer exist:
- Async request-reply with polling. The server acknowledges, the client asks "is it done yet?" until it is.
- Callbacks (webhooks). The server tells the client when it is done, by calling a URL the client registered.
- Hybrids. Polling is always available; callbacks are an optional accelerator. (Long polling, SSE and WebSockets are related variants, covered briefly below.)
This article compares them for engineering teams building or consuming integration APIs, shows a working polling implementation, and lists the failure modes that cause most incidents.
The baseline: 202 Accepted plus a status resource
HTTP has a status code designed for this. 202 Accepted means the request was accepted for processing but processing is not complete. The semantics are deliberately noncommittal: the server is not promising the work will succeed, only that it received it (RFC 9110, HTTP Semantics; see also MDN's description of 202). That is exactly why the response must carry something the client can use to find out later.
Microsoft's Azure Architecture Center documents this as the Asynchronous Request-Reply pattern, and its shape is a good template:
- The API validates the request first. An invalid request gets an immediate
400, not a202followed by an inevitable failure. - A valid request gets
202with aLocationheader pointing at a status endpoint and, optionally,Retry-Aftergiving an estimated wait. - Every successful call to the status endpoint returns
200with a body describing state (the page suggests fields such asstatus,createdAt,lastUpdatedAt, an optionalpercentCompleteand a structurederror). - When the work finishes, the status endpoint returns
303 See Otherpointing at the resulting resource. The page explains why 303 rather than 302: a 303 tells the client to issue aGETregardless of the original method, whereas some clients replay the original method after a 302.
Two details in that pattern are easy to miss. First, the status endpoint answering 200 while the operation is still running is intentional: the status resource exists and was read successfully, even though the job has not finished. Second, failures are persisted and reported through the same mechanism. The pattern recommends storing the error and returning an appropriate 4xx with an RFC 9457 Problem Details body (application/problem+json, with members type, title, status, detail and instance).
sequenceDiagram
participant C as Client
participant A as API
participant W as Worker
C->>A: POST /reports (Idempotency-Key: k1)
A->>W: enqueue job
A-->>C: 202 Accepted, Location: /jobs/42, Retry-After: 1
loop until terminal state
C->>A: GET /jobs/42
A-->>C: 200 {status: running}, Retry-After
end
W->>A: job finished
C->>A: GET /jobs/42
A-->>C: 303 See Other, Location: /reports/rpt_9
C->>A: GET /reports/rpt_9
A-->>C: 200 reportA working reference implementation
The snippets below are a minimal Flask server and a polling client. I ran both locally against each other: the client received the finished report, and replaying the same Idempotency-Key returned a 202 for the existing job instead of starting a new one. The in-memory dictionaries are placeholders; production needs a durable store and a real queue.
# server.py
import threading, time, uuid
from flask import Flask, jsonify, request, url_for
app = Flask(__name__)
JOBS = {} # job_id -> dict (use a database in production)
KEYS = {} # Idempotency-Key -> job_id
def run_job(job_id):
JOBS[job_id]["status"] = "running"
time.sleep(2) # stand-in for real work
JOBS[job_id].update(status="succeeded", result_id="rpt_" + job_id[:8])
@app.post("/reports")
def create_report():
key = request.headers.get("Idempotency-Key")
if key and key in KEYS: # replay: same job, no new work
job_id = KEYS[key]
else:
job_id = uuid.uuid4().hex
JOBS[job_id] = {"status": "pending"}
if key:
KEYS[key] = job_id
threading.Thread(target=run_job, args=(job_id,), daemon=True).start()
resp = jsonify(status=JOBS[job_id]["status"])
resp.status_code = 202
resp.headers["Location"] = url_for("get_job", job_id=job_id)
resp.headers["Retry-After"] = "1"
return resp
@app.get("/jobs/<job_id>")
def get_job(job_id):
job = JOBS.get(job_id)
if job is None:
return jsonify(type="about:blank", title="Not Found", status=404), 404, \
{"Content-Type": "application/problem+json"}
if job["status"] == "succeeded":
resp = jsonify(status="succeeded")
resp.status_code = 303
resp.headers["Location"] = url_for("get_report", report_id=job["result_id"])
return resp
resp = jsonify(status=job["status"])
resp.headers["Retry-After"] = "1"
return resp # 200 while pending/running
@app.get("/reports/<report_id>")
def get_report(report_id):
return jsonify(id=report_id, rows=42)# client.py
import random, time, requests
def create_and_wait(base, deadline_s=60):
r = requests.post(f"{base}/reports", headers={"Idempotency-Key": "demo-1"})
assert r.status_code == 202
status_url = base + r.headers["Location"]
delay = float(r.headers.get("Retry-After", 1))
end = time.monotonic() + deadline_s
while time.monotonic() < end:
time.sleep(delay + random.uniform(0, 0.25 * delay)) # jitter
s = requests.get(status_url, allow_redirects=False)
if s.status_code == 303:
return requests.get(base + s.headers["Location"]).json()
s.raise_for_status()
delay = min(max(float(s.headers.get("Retry-After", delay)), delay * 1.5), 30)
raise TimeoutError("job did not finish before client deadline")A few choices in that client matter more than they look. It honours the server's Retry-After as a floor but also backs off on its own, so a server that forgets to send the header does not get hammered. It adds jitter so a thousand clients that started together do not poll in lockstep. And it has an overall deadline: a client that polls forever is a resource leak. (Retry-After carries either a number of seconds or an HTTP date per RFC 9110; the client above handles only the seconds form, which is a reasonable simplification if you control the server.)
Idempotency: the part that makes retries safe
The initial POST is where duplicates are born. A client times out waiting for the 202, retries, and the server cannot tell a retry from a deliberate second request. The Azure pattern suggests an Idempotency-Key request header, with a duplicate key returning the existing status resource rather than enqueuing a second item. The server above does exactly that.
Be precise about the standards status. The Idempotency-Key header is described in an IETF Internet-Draft from the HTTP API working group, The Idempotency-Key HTTP Header Field. It is a draft, not a published RFC, so treat it as a convention many APIs follow rather than a ratified standard. If you adopt it, document your own rules: how long keys are remembered, what happens when the same key arrives with a different body (reject it with a clear error rather than silently returning the old result), and whether keys are scoped per tenant or per credential.
Option 1: polling in depth
Polling is the least glamorous option and the most dependable. It works through corporate proxies and firewalls, needs no inbound endpoint on the client, and is trivially debuggable with curl. The Azure documentation lists exactly these situations as reasons to prefer it: browser clients where callbacks are hard to provide, services reachable only over HTTP where the return path is blocked by client-side firewalls, and integrations with workloads that do not support webhooks.
Its costs are latency (the client learns of completion only at its next poll) and wasted requests (most polls say "not yet"). Both are tunable. The server controls the first through Retry-After and the second by making status reads cheap: serve them from a small keyed record rather than from the system doing the work.
Design points worth settling up front:
- Status vocabulary. Pick a small closed set (for example
pending,running,succeeded,failed,canceled) and document which are terminal. Clients should never infer completion from the absence of a field. - Retention. Status resources cannot live forever. The Azure pattern says to define a retention policy and mentions an
Expiresheader on the status response so clients know the window. Google's API design guidance takes the same view: AIP-151 says APIs may let operation resources expire after sufficient time following completion, with 30 days as a rule of thumb. After expiry, return a clear404or410with a Problem Details body that says the record expired, so clients can distinguish "never existed" from "too late". - Cancellation. If users can abort, the pattern suggests exposing
DELETEon the status resource. Decide what cancelling a half-finished job means for side effects already committed. - Not-found ambiguity. The Azure page warns that polling the eventual result URL and treating
404as "not ready" is unclear, because an invalid ID also yields404. Poll a status resource that exists from the moment of acceptance.
The standardised version: operation resources
If you expose many long-running endpoints, a uniform "operation" resource beats ad-hoc job shapes. Google's AIP-151 describes one: a long-running method returns an Operation whose done field flips to true, carrying either a response or an error, with metadata for progress on each GetOperation call. AIP-151 also says individual APIs must not define their own interfaces for it, and that a long-running create resolves to the resource itself (AIP-133). You do not need Google's protobuf types to borrow the idea: one consistent envelope across all slow endpoints means one polling client, one retention policy and one error format.
Option 2: callbacks and webhooks
A callback reverses the flow: the client registers a URL, and the server calls it when the state changes. Latency drops to near zero and the wasted polling traffic disappears. The price is that you have now built a delivery system, and the delivery system is the part that fails.
Stripe's webhook documentation is a useful statement of what a mature provider tells its consumers, and each point maps to a requirement on your side:
- Return a
2xxquickly, before any complex logic that could time out, and handle events asynchronously. - Expect retries: in live mode Stripe says it attempts delivery for up to three days with exponential backoff.
- Expect duplicates: "Webhook endpoints might occasionally receive the same event more than once", so record processed event IDs.
- Do not assume order: Stripe states it does not guarantee delivery in the order events were generated.
- Verify signatures against the raw request body.
The Standard Webhooks specification codifies similar conventions for providers: webhook-id, webhook-timestamp and webhook-signature headers, a signed string built from the ID, timestamp and payload, a signature header that can carry several space-delimited signatures to allow secret rotation, retries over multiple days with exponential backoff, and webhook-id as an idempotency key for consumers. Its retry guidance treats any 3xx as a failure, which matters if your receiving endpoint sits behind a redirecting proxy.
On the consumer side, the minimum viable receiver verifies, deduplicates and acknowledges. This sketch uses a generic HMAC-SHA256 over id.timestamp.body; I tested it for accept, duplicate and tamper cases, but real providers differ in encoding and secret format, so follow your provider's exact scheme:
import hashlib, hmac, time
SEEN = set() # use a unique-constrained table in production
def verify(secret: bytes, msg_id: str, ts: str, body: bytes, sig_hex: str, tol=300):
if abs(time.time() - int(ts)) > tol:
return False
signed = f"{msg_id}.{ts}.".encode() + body
expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig_hex)
def handle(secret, msg_id, ts, body, sig):
if not verify(secret, msg_id, ts, body, sig):
return 401
if msg_id in SEEN: # duplicate delivery: acknowledge, do nothing
return 200
SEEN.add(msg_id)
# enqueue(body) here; do the real work off the request path
return 200Note the order: authenticate first, deduplicate second, enqueue third. An in-memory set is only a stand-in. In production, the dedupe record and the enqueue should succeed or fail together, which is the dual-write problem the outbox pattern addresses.
Why callbacks alone are not enough
A pure-callback design has no recovery path. If the client's endpoint was down for longer than your retry window, or the client lost the event, nothing tells them the job finished. This is why the strongest designs keep the status resource as the source of truth and treat the webhook as a hint. The event payload can be tiny (job ID and new state); the receiver fetches the authoritative state from the status endpoint. That also removes most ordering problems: a late "running" event cannot overwrite a fetched "succeeded" state if the receiver always trusts the fetch.
Comparison: choosing a pattern
| Dimension | Polling (202 + status) | Webhook callback | Hybrid (poll + webhook hint) |
|---|---|---|---|
| Client needs a public endpoint | No | Yes | Optional |
| Completion latency | Up to the poll interval | Near real time | Near real time, with polling as fallback |
| Wasted requests | High if interval is short | None | Low |
| Works behind strict firewalls | Yes | Often not | Yes (falls back to polling) |
| Provider complexity | Low: a status table | High: signing, retries, dead letters, secret rotation | Highest, but reuses both |
| Consumer complexity | Low: a loop with backoff | Medium: verify, dedupe, queue | Medium |
| Failure recovery | Built in: re-read the status | Needs replay tooling | Built in via polling |
| Best for | Browser/mobile clients, partners with locked-down networks, simple integrations | Server-to-server integrations needing low latency | Public APIs with mixed client types |
The Azure guidance names cases where async request-reply is not the right fit: when a purpose-built notification service exists, when results must stream in real time (consider Server-Sent Events), when a client must collect many results with latency mattering (consider a message broker), when persistent connections such as WebSockets are available, or when the network allows open ports for callbacks. Read that list as the boundary of this article: if one of those applies, use that tool instead.
Long polling, SSE and WebSockets in one paragraph
Long polling holds the status request open until something changes, cutting latency without a public endpoint, but the Azure page flags the "complexity around connection management and timeouts." It also reintroduces the very thing you were avoiding, open connections that intermediaries may kill. SSE suits one-way progress streams to browsers. WebSockets suit bidirectional, long-lived sessions. All three are reasonable additions for progress reporting. None replaces a durable status resource, because connections drop and clients restart.
Common mistakes
- Returning
202before validating. Accepting a request that you already know is malformed pushes a predictable error into the async path. Validate synchronously, fail fast with400. - No idempotency on the initial request. Timeouts plus retries equals duplicate work. Decide how keys behave before launch, not after the first duplicate invoice.
- Status endpoint that is expensive. If every poll hits the system doing the work, polling clients become a denial-of-service on your own pipeline. Write state to a lightweight record as the job progresses.
- Missing or ignored
Retry-After. Without guidance, clients choose their own intervals, usually too aggressive. With guidance but without jitter, they synchronise. - Treating the webhook as the source of truth. Events arrive late, twice, or out of order. Fetch the state.
- Redirecting webhook endpoints. Under the Standard Webhooks guidance a
3xxresponse counts as failure. Receivers behind redirecting load balancers silently miss events. - Errors only in logs. A failed job must produce a terminal, queryable failure with a Problem Details body, not a status that stays
runningforever. - Unbounded retention or no expiry story. Either storage grows forever or old IDs return a confusing
404. Document the window. - Breaking the status shape. Operation envelopes become public contracts. Changing a field's meaning breaks every integrator; version and announce changes the way you would any other API change.
Implementation checklist
Starting the operation
- Validate synchronously; return
400for bad input. - Return
202, aLocationheader to the status resource andRetry-After. - Support an
Idempotency-Key; define scope, lifetime and mismatch behaviour. - Persist the job record before acknowledging.
Status resource
- Closed, documented status vocabulary with terminal states marked.
200while in progress;303to the result on success.- Failures stored and exposed as
application/problem+json. - Cheap reads; retention policy and expiry response defined.
- Cancellation semantics documented if offered.
Webhooks (if offered)
- Signed payloads with timestamp and unique event ID; support secret rotation.
- Retry with exponential backoff over a documented window; dead-letter after exhaustion.
- Small payloads that point back to the status resource.
- Replay tooling or a list-events endpoint for consumers that missed deliveries.
- Documentation stating that duplicates and reordering are possible.
Clients
- Honour
Retry-After; add backoff and jitter; enforce an overall deadline. - Webhook receivers: verify signature on the raw body, deduplicate by event ID, acknowledge fast, process off-path.
- Reconcile periodically by polling for jobs that have been non-terminal too long.
When to build which: a practical decision path
If you are designing a new API today and do not know your clients yet, ship polling first. It covers every client type, it is the recovery path for everything else, and it is cheap to run. Add webhooks when integrators ask for lower latency or when polling volume becomes a measurable cost, and add them as hints layered over the same status resource. If you expose many slow endpoints, standardise the operation envelope early; retrofitting one across twenty endpoints is far more painful than adopting it for the first.
If you are on the consuming side of a third-party API, assume you will need to poll even if webhooks exist: reconciliation by polling is how you detect the events you never received.
How Syslabs helps
Syslabs designs and builds API and integration layers for teams who need these patterns to behave under real load: async job APIs with idempotent intake, webhook delivery pipelines with retries and dead-letter handling, and the monitoring that tells you when a stuck job is stuck. If you are untangling a timeout-prone integration or planning a public API with long-running operations, we can review your design against the checklist above and propose a migration path that does not break existing consumers. Book a technical conversation.
References
- RFC 9110: HTTP Semantics, IETF
- RFC 9457: Problem Details for HTTP APIs, IETF
- Asynchronous Request-Reply pattern, Microsoft Azure Architecture Center
- AIP-151: Long-running operations and AIP-133: Standard methods: Create, Google API Improvement Proposals
- Receive Stripe events in your webhook endpoint, Stripe documentation
- Standard Webhooks specification
- The Idempotency-Key HTTP Header Field, IETF Internet-Draft
- 202 Accepted, MDN Web Docs



