The Async Completion Problem

After returning 202 Accepted, how does the client know when the job is done? Two approaches: the client polls for status, or the server pushes the result to the client.

Polling Pattern

// 202 response body
{ "jobId": "abc-123", "statusUrl": "/jobs/abc-123" }

// GET /jobs/abc-123 while in progress
{ "status": "processing", "progress": 42 }
// when done
{ "status": "complete", "result": { "url": "/reports/abc-123.pdf" } }

Polling is simple but inefficient — most responses return still processing. Add exponential backoff and return an ETA field so clients set an intelligent retry interval.

Webhooks Pattern

// Client registers callback URL
POST /export
{ "webhookUrl": "https://client.com/hooks/report-done" }

// Server POSTs result on completion
POST https://client.com/hooks/report-done
X-Signature: sha256=hmac_of_body
{ "jobId": "abc-123", "status": "complete" }

Always sign webhooks with HMAC-SHA256. The client verifies the signature before processing. Webhooks eliminate polling overhead but require the client to expose a public endpoint. Use polling for simple integrations and webhooks for production async workflows where latency and efficiency matter.