Webhooks or polling

The decision, in one table#

The row that decides most real cases is the fourth. Events are cheaper per unit of freshness and more expensive per unit of engineering: a receiver is a service with its own uptime, its own TLS, its own secret to rotate and its own way of failing quietly.

What polling costs here, concretely#

The public routes send Cache-Control: public, max-age=300, and the corpus changes on a deploy rather than on a request. Polling faster than five minutes buys nothing but a cached copy of the answer you already had.

# The cheap change detector: one small object, not the whole corpus.
GET /api/public/docs/status HTTP/1.1
Host: connectbyjbrh.com

# Compare `generated` and `version` with your last copy.
# They move on a rebuild and not within one.

A fifteen-minute schedule on that one object is 96 requests a day against a limit of 240 a minute — not a consideration. Only when generated moves do you fetch what actually changed, which is the pattern that keeps a documentation client both current and quiet.

The failure mode is the pleasant one: if your poller dies for a day, the next successful poll sees current state and nothing needs reconciling. Nothing was in flight, so nothing was lost.

What events would cost, and the honest availability#

A receiver has an irreducible shape: a public endpoint, signature verification before parsing, a fast acknowledgement, a durable queue behind it, and a de-duplication store keyed on the event id. Skip any one of them and you have a receiver that works until it does not — usually the first time a retry arrives during a slow database write.

The end state deserves planning before the happy path. A receiver that keeps failing is retried with backoff and then paused, and the pause is visible in the workspace rather than to your monitoring. Alert on 'no events since a plausible interval' at your own end, or you will discover the pause from a person rather than from a graph.

The shape most systems end up with#

Where both are available, the durable answer is rarely one or the other. An event is a trigger to read, not a record to store: it says something happened and identifies what, and the receiver then reads the current state of that thing. A slow poll runs underneath as a safety net, catching whatever a pause or a bug dropped.

• Event → read → act. The payload carries identifiers and a reason; the record carries the truth.
• A reconciliation poll, hourly or daily, over the same domain the events cover. It should normally find nothing, and the day it finds something is the day it paid for itself.
• One idempotent handler for both paths, keyed on the same identity. Two code paths for the same outcome is how a webhook system and its safety net start disagreeing.

For a documentation or status client on Connect today, that whole structure collapses to its second bullet — a slow poll of one small object, which is both what is available and what the data actually warrants.

Questions#

Related#

• Outbound webhooks
• The AsyncAPI description
• The machine-readable documentation
• Designing a resilient client
• The product status manifest