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:

  1. Async request-reply with polling. The server acknowledges, the client asks "is it done yet?" until it is.
  2. Callbacks (webhooks). The server tells the client when it is done, by calling a URL the client registered.
  3. 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 a 202 followed by an inevitable failure.
  • A valid request gets 202 with a Location header pointing at a status endpoint and, optionally, Retry-After giving an estimated wait.
  • Every successful call to the status endpoint returns 200 with a body describing state (the page suggests fields such as status, createdAt, lastUpdatedAt, an optional percentComplete and a structured error).
  • When the work finishes, the status endpoint returns 303 See Other pointing at the resulting resource. The page explains why 303 rather than 302: a 303 tells the client to issue a GET regardless 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).

mermaid
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 report

A 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.

python
# 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)
python
# 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 Expires header 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 clear 404 or 410 with 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 DELETE on 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 404 as "not ready" is unclear, because an invalid ID also yields 404. 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 2xx quickly, 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:

python
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 200

Note 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

DimensionPolling (202 + status)Webhook callbackHybrid (poll + webhook hint)
Client needs a public endpointNoYesOptional
Completion latencyUp to the poll intervalNear real timeNear real time, with polling as fallback
Wasted requestsHigh if interval is shortNoneLow
Works behind strict firewallsYesOften notYes (falls back to polling)
Provider complexityLow: a status tableHigh: signing, retries, dead letters, secret rotationHighest, but reuses both
Consumer complexityLow: a loop with backoffMedium: verify, dedupe, queueMedium
Failure recoveryBuilt in: re-read the statusNeeds replay toolingBuilt in via polling
Best forBrowser/mobile clients, partners with locked-down networks, simple integrationsServer-to-server integrations needing low latencyPublic 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

  1. Returning 202 before validating. Accepting a request that you already know is malformed pushes a predictable error into the async path. Validate synchronously, fail fast with 400.
  2. No idempotency on the initial request. Timeouts plus retries equals duplicate work. Decide how keys behave before launch, not after the first duplicate invoice.
  3. 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.
  4. Missing or ignored Retry-After. Without guidance, clients choose their own intervals, usually too aggressive. With guidance but without jitter, they synchronise.
  5. Treating the webhook as the source of truth. Events arrive late, twice, or out of order. Fetch the state.
  6. Redirecting webhook endpoints. Under the Standard Webhooks guidance a 3xx response counts as failure. Receivers behind redirecting load balancers silently miss events.
  7. Errors only in logs. A failed job must produce a terminal, queryable failure with a Problem Details body, not a status that stays running forever.
  8. Unbounded retention or no expiry story. Either storage grows forever or old IDs return a confusing 404. Document the window.
  9. 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 400 for bad input.
  • Return 202, a Location header to the status resource and Retry-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.
  • 200 while in progress; 303 to 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