Polling vs webhooks: ask for a change or receive an event?Delivery is not the same as completed processing

Polling puts the schedule with the reader

With polling, a client periodically requests the current state. A job may still be running when the response arrives. The client waits and asks again under a bounded policy. A longer interval can reduce requests but delay detection; a short interval can increase load without making the job finish sooner. The interval is a product and capacity decision, not a universal constant.

A browser can often poll an authenticated API without exposing a new public inbound server. It still needs authorization, cancellation and sensible handling for failures or rate limits. Stop polling when the task completes, the user cancels or the application no longer needs the result. A retry loop should not continue forever after its page is closed.

Webhooks put delivery with the producer

A webhook subscription asks a service to send an HTTP request to a configured receiver when an event occurs. That receiver is usually a server endpoint, not the user’s browser tab. It needs to be reachable and able to process the producer’s event format. The application may then update the browser through another mechanism.

This distinction prevents a common diagram error: drawing a webhook as though it directly updates every open browser. Producer-to-receiver delivery and receiver-to-reader display are separate paths. A job-status webhook can update stored state while the user is offline; the user still needs a way to retrieve the current result later.

Accept quickly without pretending the work is done

A receiver can validate an event and arrange for background processing rather than making the sender wait for an expensive task. Exactly when to acknowledge depends on the durable handoff and the provider’s contract. Returning success before safely recording necessary work can lose information if the receiver crashes immediately afterward.

Provider retry behavior differs. GitHub’s documentation, for example, discusses responding promptly and explicitly redelivering missed deliveries; it is not a universal promise of automatic retries. Check the actual provider rather than assuming that every webhook is retried forever, delivered once or delivered in order.

A duplicate must not repeat an effect

Our synthetic receiver sees event e-17 twice and e-18 once. It identifies deliveries by the event identifier and applies two effects, not three. The fixture verifies one ignored duplicate. This is a tiny in-memory demonstration: restarting it loses its remembered identifiers, and concurrent processes would not share that set.

A production implementation may need durable deduplication, atomic storage and a stable business operation key. Recording “seen” before a failed effect can suppress necessary recovery; recording it afterward can permit duplication if the process crashes in between. Design the operation and reconciliation together. A Set in a tutorial is not an exactly-once system.

Authenticate the delivery, then validate its content

An event-shaped request is not proof of its sender. Follow the provider’s signing and verification procedure, protect the shared secret where applicable and keep HTTPS verification enabled. Signature checks usually depend on the exact signed bytes, so parsing and reserializing the body can change the material being verified.

After authenticity checks, validate the event type, action, identifier and resource scope. A correctly signed event can still be irrelevant, old or insufficient to determine current state. For an out-of-order update, consult the producer’s state/version rules instead of blindly overwriting newer information.

Use reconciliation when completeness matters

Notifications can be a prompt to fetch authoritative state. A bounded periodic reconciliation can detect gaps when the provider supports it. This is a different responsibility from repeatedly sending the same side effect. Record an uncertain outcome and investigate it before replaying a write whose first result is unknown.

Pick the simpler supported contract

For occasional changes and a small audience, bounded polling can be sufficient. Webhooks can reduce unnecessary status requests when a trusted reachable receiver exists. A hybrid can be useful, but adds responsibilities. Our exercise sends no real webhook and uses no external job; it checks duplicate handling for stated inputs, not transport security or delivery guarantees.

References

Sources used to check the explanations and examples are listed below.

1. GitHub: webhooks and polling
2. GitHub: signatures, response timing and redelivery

Found a mistake? Send a correction with this lesson’s title, URL and disputed detail. No login needed.