Polling vs Webhooks for Desk Notifications
Status Light is a desk signal with a black body and three domed red, amber and green lenses. Whether its state comes from polling or webhooks is a software architecture decision, and its own catalogue entry does not confirm how automation reaches it.
What does each pattern actually require from you?
A webhook needs a reachable HTTPS receiver, provider configuration, signature verification, replay protection, durable event handling and a route from that receiver to the desk. Polling needs a scheduled local process, API authentication, request filtering, rate-limit discipline and a stored record of the last observation.
Both need a state model, logs and an unknown condition. Neither makes a raw provider status meaningful without selecting the exact project, branch, workflow or agent involved.
When do webhooks earn their setup cost?
Use webhooks when low delay matters, the provider offers signed events and one maintained receiver will serve several consumers. They also help when querying current status is expensive or cannot reveal every transition. A hosted service with proper monitoring is a better receiver than an intermittently sleeping laptop.
Expect duplicate or out-of-order delivery. Verify identity first, normalize events, make processing idempotent and compare event time or sequence before replacing current state.
When is polling simply better for one desk?
Polling often wins when only one local display needs a small number of statuses. It requires no inbound network path, naturally recovers the latest state after downtime and can be removed by stopping one process. Use the provider's structured API, not screen scraping.
Choose an interval that reflects human urgency and published limits. Cache identifiers, request only necessary fields and back off on errors. A desk light rarely needs continuous network traffic.
How do the failure modes differ?
A webhook can be misconfigured, blocked, delivered twice or accepted while the local desk worker is offline. A poller can be stale, rate-limited or silently unauthorized. Webhooks need a delivery queue and inspection log; polling needs a last-success timestamp and explicit stale threshold.
The Status Light should show neither green nor red when the data path is unknown. Confirm the hardware interface, test loss and recovery for the chosen pattern, and keep a screen-based source of truth for investigating the colour. Measure reliability from the user's perspective: how long a wrong state remains visible, whether missed events are repaired, and whether a restart recovers without manual work. Keep a simple health record for the adapter itself. If the maintenance cost exceeds the value of an ambient signal, return to a conventional terminal notification.