Card 06/ 09
Polling vs Webhooks for a Job's Result
Polling is simple and wastes requests; webhooks are prompt and need a receiver the sender can reach.
Polling and webhooks both deliver a result the client did not wait for. Polling has the client ask until the answer changes, which works from anywhere but spends requests on "not yet". Webhooks have the server announce the change, which is prompt and cheap but needs a receiver the server can reach and the receiver to handle retries and forgeries.
| Property | Polling | Webhooks |
|---|---|---|
| Latency | Up to one polling interval late | Seconds after the event |
| Requests spent | Many, most answered running | One per event, plus retries |
| Client needs | Only outbound HTTP | A public HTTPS endpoint |
| Security work | The usual API authentication | Signature, timestamp and secret storage |
| When a party is down | The client asks again when it returns | The sender retries, then may give up |
| Order and duplicates | The client reads the current state | Events may repeat or arrive out of order |
Choose polling when clients cannot expose an endpoint, such as mobile apps, browser code and scripts, when jobs are few, or when a delay of one interval does not matter.
Choose webhooks when clients are servers, events are frequent or unpredictable, or polling would cost both sides more than a receiver does.
Offer both where the API serves many kinds of client. The webhook says something changed; the status resource stays the source of truth a client can read at any time, including after a missed webhook.
A common hybrid. Send a thin webhook carrying only the event type and resource link, and let the receiver read the resource. It sidesteps out-of-order payloads, because the receiver always reads the latest state.
← → move through sections and cards