Use webhooks when a source can push useful change notifications to a reliable receiver, polling when the source offers a queryable change boundary or push is unavailable, and event streaming when retained ordered partitions and independent consumers justify the operating model. Choose from delivery contracts, traffic, freshness and recovery requirements. A hybrid often combines fast notification with reconciliation.

Key takeaways

• Webhook retry and ordering behavior are provider-specific.
• Polling needs stable cursors or a carefully designed change window.
• Streaming retention and checkpoints enable replay only within the supported data and processing contract.
• Technical receipt is different from completed business processing.

Webhook vs polling vs event streaming

GitHub’s webhook guidance illustrates provider-specific requirements for secrets, HTTPS, timely responses and missed-delivery handling. Treat those details as GitHub’s contract, not as universal behavior for every webhook provider.

Azure Event Hubs terminology describes an append-only event log, ordered partitions, consumer groups, offsets and checkpoints. Other platforms and configurations must be checked for their own delivery, retention and recovery behavior.

A webhook endpoint can enqueue work into a stream or queue. A polling worker can publish meaningful changes for other consumers. The choices describe parts of a pipeline and do not have to be exclusive.

A traffic and freshness calculation

Illustrative arithmetic, not measured traffic: 1,000 independent polling subscriptions checked every minute create 1,000 scheduled calls per minute, or 1,440,000 calls over a 24-hour day, before pagination, failures or retries.

If each check returns no changes, the transport cost still exists. A delta endpoint or batching can alter that model significantly. Compare the source’s actual API contract rather than assuming every tenant needs a full resource scan.

Under an ideal fixed one-minute polling schedule with uniformly timed changes, schedule-induced detection delay averages roughly 30 seconds and can approach one minute. Add query time, throttling, failures and processing delay to estimate end-to-end freshness. This is a scheduling model, not an availability guarantee.

For webhooks, estimate change rate, delivery payload size, retries and burst concurrency. For streams, estimate ingress, retained storage, consumer reads and processing. A low-volume notification workflow may not need a streaming platform, while many independent consumers may justify one.

Define the service objective in business terms: how soon a valid source change must become usable in the destination. Measure source occurrence, receipt, durable acceptance and final processing separately where available.

Delivery guarantees, retries and reconciliation

Webhook receiver

Validate the provider’s authentication or signature mechanism against the correct request representation. Keep transport security enabled and secrets out of URLs. Reject invalid deliveries before business processing.

Acknowledge according to the provider’s deadline and your durability contract. Returning success before work is safely accepted can lose changes after a crash. Running a slow business workflow inline can instead trigger provider timeouts and duplicate deliveries.

Use delivery or business-operation identity where the provider supports it, with durable duplicate handling appropriate to the action. Validate event type and version. Do not assume a notification contains the latest state if deliveries arrive late or out of order.

Polling worker

Prefer a source-supported delta cursor when available. Persist progress only after the corresponding work is safely handled. Define pagination and deletion behavior, cursor expiry and recovery from an interrupted run.

Timestamp windows need tie-breakers, stable ordering and a policy for late updates. An overlap window can reduce missed-boundary risk but creates duplicates that must be handled. A local clock timestamp alone is not proof of the source’s committed change position.

Streaming consumer

Choose partition keys from required ordering and distribution. Keep processing checkpoints consistent with persisted results. A consumer restart may reprocess events, so design the action and state update to tolerate the platform’s delivery behavior.

Monitor lag relative to retention. Replay is useful only while required history remains available and compatible readers can interpret it. Reconstructing a read model must not unintentionally resend external business actions.

A practical decision flow

Does the source expose a suitable retained event stream?
├─ Yes: need independent consumers/replay? → evaluate streaming
└─ No or unnecessary:
   Does it provide reliable, useful webhooks?
   ├─ Yes → webhook receiver + durable processing + reconciliation
   └─ No → supported delta/polling API + cursor + bounded schedule

For every path: verify freshness, duplicates, ordering, access and recovery.

Source capability is a hard constraint. A destination cannot invent reliable change history from an API that returns only current state without any suitable change marker. Clarify what can be detected, including deletions and intermediate transitions.

If the business needs every transition, a periodic current-state snapshot may be insufficient even when its final values look correct. Match the integration semantics to the required outcome before comparing implementation effort.

Three illustrative integration examples

CRM customer updates

A fictional CRM supplies signed webhooks for customer changes and a supported query API. The receiver validates deliveries, persists accepted work and processes it asynchronously. A scheduled reconciliation detects missed notifications. The design treats webhook receipt and destination completion as distinct states.

Legacy inventory export

An older system offers a stable delta query but no push mechanism. A polling job persists the source cursor and processes bounded pages. It handles retries and expired cursors through a reviewed resynchronization procedure. Increasing poll frequency is evaluated against source capacity and the freshness objective.

Operational telemetry for several teams

A telemetry platform needs multiple consumers and retained history. A partitioned stream can support separate processing positions and replay. The team selects keys, retention and capacity from the workload, then tests lag and restart behavior. This is a proposed architecture example, not a throughput benchmark.

Validation and operating checklist

• Document source capabilities and exact provider guarantees.
• Define freshness and business completion objectives.
• Test duplicates, late arrival and out-of-order data.
• Rehearse receiver downtime or an interrupted polling run.
• Test cursor expiry, retention gaps and resynchronization.
• Measure burst behavior, backlog age and source throttling.
• Verify tenant scope, signatures or credentials and safe logs.
• Assign ownership for failed work, replay and reconciliation.

Keep a recovery record for each failure: what was accepted, what may already have completed and which operation can safely be retried. “Retry all” is insufficient for actions such as invoicing or provisioning.

For the wider platform choice, use the enterprise integration comparison, and the messaging guide for queue-processing responsibilities.

Common questions

Match delivery behavior to the business objective

Bring source APIs, change rates and freshness requirements. Request an API integration architecture review to choose notification, polling and recovery patterns for your systems.