/webhooks endpoint, no event subscription mechanism, no push notifications when records change in VOMO. For partner integrations that need to react to changes — sync new participations to a CRM, detect waiver completions, mirror Project schedules to external calendars — polling is the only path.
This page covers why that’s the design, what polling looks like in production, and the architectural shapes that work well. The next pages in this group walk through the specific patterns for each resource family.
Why polling
CRM+ and Raise both have rich webhook surfaces — subscribe to events, receive push notifications when they fire, react in near-real-time. The Volunteer API does not. Partner integrations need an alternative for change detection.What polling means
Polling is the pattern of periodically querying the API for changes since the last query. Instead of being told “this record changed,” the integration asks “what has changed?” on a schedule: The fundamental pattern: schedule + filter + checkpoint. A scheduled job runs at intervals, queries with a time filter for changes since the last checkpoint, processes the changes, and advances the checkpoint to the latest record seen.Trade-offs vs. webhooks
Polling and webhooks each have strengths:
Polling is simpler to set up but continuously costs more in API requests. For most Volunteer integrations, the trade-off is acceptable — the data doesn’t change second-to-second, and partner-side infrastructure can run polling cheaply.
The core polling pattern
A minimal polling worker has four parts:1
Scheduler
A cron job, scheduled task, or interval timer that fires the polling worker periodically.
2
Checkpoint storage
Per-customer persistent storage of “the last
updated_at we successfully processed.”3
Query
GET /users?updated_after={checkpoint} (or the equivalent for whatever resource).4
Process and advance
Process each result; advance the checkpoint to the latest
updated_at actually seen.JavaScript
Which resources support change detection
Most list endpoints acceptupdated_after (and the related time filters), making them suitable for polling:
The seven endpoints with full time filters cover the resources that change frequently and need detection. For the others, alternative strategies apply (full re-read with deduplication, transitive detection through the parent resource, etc.).
What updated_at captures — and what it misses
The updated_at filter captures changes to the record itself. What changes count varies by resource:
What
updated_at typically does not capture:
These gaps matter for designing the polling architecture. If your integration needs to detect new participations, polling
/users with updated_after is not sufficient — you’d need to poll Project Dates separately, or rely on the User’s last-known participation list growing.
See Detecting User Changes for the User-specific patterns and Reconciliation Patterns for what to do about the gaps.
Poll cadence — how often to poll
The right interval depends on the business need and the rate budget:Cadence by resource
Different resources benefit from different cadences. A reasonable per-resource breakdown:
The cadence may also vary by customer — a customer with active daily operations needs faster polling than one with a once-a-week volunteer event.
Why not just poll constantly?
Each poll consumes API request budget. The math:- A 5-minute poll cadence = 288 polls/day per resource per customer
- Across 7 resources, that’s ~2,000 polls/day per customer
- Add pagination (with 15-records-per-page) and the actual request count multiplies
Architectural shapes
A few common patterns for organizing polling work:Shape 1: per-resource workers
One worker per resource, each running at its own cadence: Clean separation, easy to reason about, easy to scale individually. The downside: more cron schedules to manage, more checkpoint state per customer.Shape 2: unified poll cycle
One worker that polls multiple resources in sequence: Simpler scheduling, easier to monitor as a single workflow. The downside: every resource polls at the same cadence even when faster or slower would be more efficient. For most partner integrations, Shape 2 (unified cycle) at 15-30 minute intervals is a reasonable starting design. Move to per-resource workers if you find that one resource needs significantly different cadence than the others.Shape 3: event-driven within a workflow
For integrations where changes in one resource trigger queries in others: The User-change poll triggers cascading fetches for related data. Useful when the partner integration needs to react to the full context of each change. The downside: many more API requests. Use sparingly and cache aggressively.The role of reconciliation
Polling alone misses some cases:
The mitigation is reconciliation — a separate, less-frequent process that audits the actual state against expected state and catches gaps:
The combination of polling + daily reconciliation produces most integrations’ production-grade reliability. See Reconciliation Patterns for the full pattern.
Polling vs. one-time sync
Polling is for ongoing change detection. For one-time operations — initial onboarding, migration, full data dump — use a separate full-state sync pattern:
The three patterns layer:
See Sync Architecture Patterns for the broader picture.
Common pitfalls
A few mistakes that surface in production polling integrations:Pitfall 1: advancing the checkpoint to “now” instead of to the latest record
updated_at between startTime and endTime — but the next poll uses startTime as the lower bound, missing them.
The right pattern is to advance to the latest updated_at actually observed in the response:
Pitfall 2: processing failures silently advance the checkpoint
If your worker processes records, encounters an error mid-batch, but still advances the checkpoint, the missed records are gone:Pitfall 3: not throttling polling against the rate budget
Polling that runs concurrently with other integration work can exhaust the rate budget. Use a shared throttled client:Pitfall 4: polling too frequently for the use case
A 1-minute poll cadence consumes 60× the rate budget of an hourly one. Audit your polling cadences against actual freshness requirements — often “near-real-time” is a comfort goal, not a hard need.Production checklist
Before deploying polling-based change detection:- Each resource has a defined polling cadence aligned with business needs
- Checkpoints are persisted per-customer in durable storage (not just in-memory)
- Checkpoint advancement uses the latest
updated_atactually seen, not wall-clock time - Failures during processing don’t silently advance the checkpoint
- Failed records go to a dead-letter queue for retry / investigation
- Rate-limit-aware throttling is in place (shared across polling workers)
- A daily reconciliation pass catches missed records
- Per-customer monitoring tracks: poll success rate, processed-records counts, lag time (max
updated_atto “now”), and dead-letter queue depth - Alerts fire on: sustained
5xx/429errors, stalled checkpoints, growing DLQ - Customer onboarding includes an initial full sync, not just turning polling on
Where to go next
Detecting User Changes
The User-specific polling pattern with checkpoint advancement and the participation-detection caveat.
Detecting Project Changes
The Project-specific polling pattern with schedule-change considerations.
Reconciliation Patterns
The companion pattern that catches what polling misses.
Change Detection Best Practices
The cross-cutting practices: checkpointing, idempotency, drift detection.