Choose webhooks or polling without missing changes

Start with the change you cannot afford to miss

A booking is cancelled in one tool, but the dispatch list still shows the visit. A quick webhook would help when delivered; a scheduled query could also find the change later. Neither method alone says whether the dispatcher saw the corrected list before leaving. Write down the business action and its latest safe decision time before choosing a transport.

This guide answers one design question: how will this workflow detect relevant changes and reconcile delayed, duplicated or missed ones? The system-of-record guide decides which tool is allowed to author the value. The API-integration checklist checks whether the intended account actually exposes the required event or query. Here the choice is between supported detection paths, with an observable way to find gaps.

Compare webhook, scheduled query and change feed

A webhook is a provider-initiated notification to a receiver you operate. It can start work promptly, but your receiver, subscription and vendor delivery path must all be healthy. Inspect exactly which create, update, delete and cancellation cases the event covers. Some notifications identify only a changed object, so the receiver must fetch the current record before acting. Microsoft Graph documents this distinction between basic change notifications and resource data.

Polling is a client-initiated read on a schedule. It can fit a workflow whose deadline is measured in hours, provided the vendor exposes a supported query that can reveal all relevant changes, including deletions. The interval is a business choice bounded by API quotas, pagination, query semantics and the acceptable delay. GitHub recommends webhooks for its API, and, when polling is necessary, a fixed schedule, conditional requests and any advertised minimum poll interval. Microsoft Graph warns that continuous scans can trigger throttling and recommends change tracking or notifications when available.

A change feed or delta query is a pull path that returns changes since a saved cursor. It can be more efficient than scanning every record, but a cursor has its own rules: complete every page, persist the new cursor only after durable processing, and handle expiry or reset. Microsoft Graph documents next links, delta links, possible replays, processing delays and reset conditions. These are Graph behaviors; verify the chosen provider before copying the design. A hybrid of notification for speed and delta or bounded query for completeness is often worth evaluating when both are supported.

Copy the detection and reconciliation matrix

Download the CSV above. Its ten columns and blank row let one workflow compare alternatives using the same decision criteria. The completed rows are explicitly fictional. Use one row per event class and candidate method; a successful test of “created” does not prove “cancelled” or “deleted”. Do not put real customer details, access tokens or webhook secrets in a shared worksheet.

• Change and business deadline | Candidate method | Coverage and authoritative read | Vendor capability and account evidence | Detection cadence and quota | Stable identity and duplicate rule | Ordering and freshness rule | Gap discovery and replay window | Reconciliation owner and acceptance test | Decision and open condition.
• Set the deadline from the next business action: for example, before dispatch rather than “near real time”. Measure observed worst-case detection and processing time in a safe test against that gate.
• Write the exact event types or query filters, deleted-record behavior, available record IDs and supported history window. “Has an API” is not coverage evidence.
• Estimate reads per interval across all connected accounts and pages, then compare with the vendor’s current plan and rate-limit responses. Do not invent a universal safe polling frequency.
• Name how a repeated delivery maps to one intended business effect, how a late event is checked against current source state and how a receiver outage is repaired. Finish with an owner, test and go, conditional or no-go decision.

Design the loop that finds a silent gap

Keep a durable checkpoint for the last fully processed change or completed query window. On each run, record the source interval or cursor, pages read, records considered, successful outcomes and unresolved exceptions. Advance the checkpoint only when all pages and intended updates have been durably accepted. If the provider offers a change token, follow its expiry and reset behavior; if it offers only an updated-since query, test whether timestamp ties, late indexing and deletes require an overlap window or periodic full comparison. An overlap creates repeats, so deduplication is part of the design.

Compare the authoritative source with the destination by stable record ID and the values or versions that matter to the next action. A count alone can hide one missed cancellation and one duplicate booking. Keep unresolved mismatches visible with a named operator and a safe pause or manual check before consequential work. A webhook delivery log is useful evidence of attempts, but it is not evidence that every relevant source change was applied downstream.

Recovery is provider-specific. GitHub says failed webhook deliveries are not automatically redelivered and documents inspecting failures and requesting redelivery. Stripe documents automatic retries for a limited period, manual resend and a procedure for processing undelivered events; it also says event order is not guaranteed. Microsoft Graph documents lifecycle notices for certain resource types and delta query to find missed changes. Verify both the chosen account’s recovery window and whether a source query can independently prove current state. When neither exists, do not promise complete synchronization.

Make repeated and out-of-order signals safe

Use the provider’s event or delivery identifier to recognize a repeated signal, then guard the resulting business action with its own stable record and action key. Those are different checks: one prevents reprocessing a delivery; the other prevents a duplicate downstream effect if distinct signals describe the same change. Stripe documents both repeated event IDs and cases where separate event objects refer to the same object and event type. GitHub retains the same delivery ID when a delivery is redelivered.

Do not assume arrival order is source order. When an older signal arrives after a newer one, read the current authoritative object or compare a provider-supported version before changing the destination. Stripe explicitly does not guarantee event ordering. For a consequential action, keep an uncertain or conflicting item in a review state rather than letting the last received payload silently win. The automation-failure-recovery guide handles retry budgets, operator alerts and manual continuation after a failed action.

Secure the receiver and test a real interruption

A webhook endpoint is an exposed input. Use HTTPS, subscribe only to needed events, validate the provider’s signature against the unmodified payload where supported, and store secrets outside source code. GitHub documents HMAC signature validation and recommends a fast response with queued processing. A successful HTTP acknowledgement should mean the event was safely accepted for processing; it should not be reported as the business outcome.

With synthetic records, test an ordinary change, repeat, delayed signal, reversed order, receiver outage, expired or reset cursor, deletion and rate-limit response. Restore the receiver and show which source records were discovered, which downstream state changed once, and which exceptions remain open. Respect Retry-After or other provider instructions when the read path is throttled. If the test cannot prove a complete repair within the business deadline, lengthen the tolerated delay, add a supported read path or keep a manual gate.

Hypothetical example: a cancelled repair visit

Imagine an invented repair business with a fictional booking tool and dispatch board. The dispatcher must confirm each appointment against the booking tool before assigning a technician. The fictional vendor offers an appointment-change webhook and an updated-record query, but its cancellation event coverage and deleted-record behavior are unverified. These are planning assumptions, not a Kinetivy client, integration or measured result.

The team tests a candidate hybrid. A webhook prompts a quick read of the appointment by stable ID; a scheduled bounded query checks changes since the last completed checkpoint. A cancellation arrives twice after a later reschedule. The handler recognizes the repeated event and reads the current booking record before changing the board, so arrival order does not determine the slot. The dispatcher still checks the booking source before assignment until a test proves cancellation coverage and the query finds every missed change within the agreed window.

In the matrix, the hybrid remains conditional: a synthetic outage must show that the query catches a cancellation made while the receiver was down, including every result page and a deletion if the vendor represents cancellation that way. If the vendor cannot expose the needed state, the team retains the manual pre-dispatch check and does not claim an automatically current board. The CSV rows are fictional examples of decisions, not vendor guarantees.