API Style & Pattern Comparisons
Side-by-side trade-offs. Neither column wins — the consumer environment, the data shape and the operational budget decide.
Polling vs Webhooks
The consumer asks "anything new?" on its own schedule vs the provider calls the consumer when something happens — trading wasted requests for delivery infrastructure.
Consumers can't host an endpoint (CLIs, mobile apps, scripts), events are rare per consumer, or near-real-time isn't required.
Thousands of consumers poll every few seconds and 99.9% of responses are "nothing yet" — you're serving heartbeats, not data.
Consumer controls pace and retry; provider stays stateless; failure recovery is just the next poll.
Poll intervals creep down chasing latency until the polling load is the capacity problem.
Capacity for mostly-empty responses; rate limits and ETag/304 support to keep the herd affordable.
Many consumers need low-latency notification of events they'd otherwise poll for constantly — payments settling, jobs finishing.
Consumers are unwilling or unable to run a secured, public HTTPS endpoint with dedup and signature verification.
Sub-second latency at near-zero steady-state cost; one delivery per event instead of N polls per consumer.
A consumer endpoint goes down and nobody designed retries, dead-lettering or redrive — events silently vanish.
A delivery pipeline with retry schedules, signatures, per-endpoint health tracking, dead-letter queues and a redrive console.
| Dimension | Polling | Webhooks |
|---|---|---|
| Latency | Bounded by poll interval | Seconds or better, event-driven |
| Who runs infrastructure | Provider absorbs the poll load | Both: provider delivers, consumer hosts and secures an endpoint |
| Failure recovery | Automatic — the next poll self-heals | Designed — retries, dead-letter, manual redrive |
| Delivery guarantees | Consumer reads current state; nothing to dedupe | At-least-once — consumers must dedupe by event id |
| Cost at scale | Grows with consumers × frequency | Grows with actual event volume |