An async request-reply API can notify completion either by having the client poll a status endpoint, or by having the client register a webhook URL that the server calls back with the result. What are the operational trade-offs between these two delivery mechanisms, and when would you choose one over the other?

## Two ends of a push-versus-pull trade-off Polling and webhook callbacks are the two dominant ways an async request-reply system delivers a completion notification back to the original caller, and they sit at opposite ends of a **push-versus-pull** trade-off. | Aspect | Polling | Webhook callback | |---|---|---| | Who owns the initiative | the client | the server | | Inbound connectivity | zero inbound network configuration on the client's side | the client must run something that accepts inbound HTTPS traffic | | Notification latency | bounded by the poll interval | near-immediate | | Fits | browsers and mobile apps | server-to-server integrations | ## Polling — the client owns the initiative With polling, the client owns the initiative: after receiving 202 and a status URL, it repeatedly issues `GET` requests until it observes a terminal state. This requires zero inbound network configuration on the client's side, which is exactly why it's the default for browsers and mobile apps, both of which typically sit behind NATs, firewalls, or app-store sandboxing that make accepting an inbound connection impractical. The cost is inefficiency: - most polls return 'still running' and are wasted work - notification latency is bounded by the poll interval rather than being immediate - server-side load scales roughly with the number of active clients times their poll frequency, which is exactly the poll-storm failure mode discussed elsewhere in this pattern ## Webhook callbacks — the server owns the initiative With a webhook callback, the server owns the initiative: the client registers a URL when submitting the job, and the server issues an HTTP `POST` to that URL once the job reaches a terminal state, carrying the result or error in the request body. This gives near-immediate notification with no wasted requests, but it inverts the trust and reachability model. The client must run something that accepts inbound HTTPS traffic, which server-to-server integrations can do easily but browser and mobile clients generally cannot. It also introduces a **security surface**: anyone who discovers or guesses the webhook URL could attempt to inject a fake completion event, so the sender must sign each payload, commonly with `HMAC-SHA256` over the raw request body using a shared secret, and the receiver must verify that signature before trusting the content. **Delivery itself is not guaranteed exactly once** over an unreliable network — if the receiver doesn't return a prompt `2xx`, the sender typically retries with exponential backoff over some bounded window, which means the receiving client must treat duplicate deliveries of the same job id as a normal, expected event and process them idempotently rather than as an error condition. If delivery keeps failing, the sender should dead-letter the notification or fall back to making the result available via a pollable status endpoint so the client isn't left permanently stranded. ## Why many APIs offer both Because the two mechanisms fit different network postures, many production APIs offer both rather than forcing one choice on every consumer: a server-to-server integration registers a webhook for low latency, while a CLI tool or script behind a restrictive firewall falls back to polling the same underlying job. - **Stripe** is a widely known example of this dual approach — most integrations subscribe to webhooks for events like payment completion, but the same information is also retrievable by directly polling the relevant resource, which matters when a webhook was missed or arrived out of order. - **GitHub Actions** and many CI/CD platforms similarly expose both a status API to poll and the option to configure a webhook, letting each consumer choose based on its own connectivity constraints and latency requirements. ## Choosing between them in practice Choosing between them in practice comes down to who controls the client's runtime environment and how much latency matters. If the caller is a backend service you don't operate but that can run a stable, publicly reachable listener, webhooks minimize both latency and wasted traffic. If the caller is a browser tab, a mobile app, or an environment behind NAT with no inbound access, polling, or a push channel like Server-Sent Events or WebSockets that the client itself initiates, is the only workable option without extra infrastructure like a message relay.