Webhooks or polling: choose for timeliness and recovery

Translate real time into a useful requirement

Real time sounds attractive but does not specify an acceptance criterion. A customer-address update might be acceptable within an hour, while an operational capacity display may need a shorter delay. Identify the decision being made and what happens when the information is older. Define the acceptable window and the response when the integration can no longer meet it reliably.

Consider a fictional order overview reviewed every working day. Clear periodic processing might suit that process better than a complex continuous event stream. Another task, such as notifying an employee about a new support request, could benefit from a timely event. Business need should drive the decision. A preferred technology is not a substitute for understanding what people do with the information and how they cope during an interruption.

Check which events actually exist

A product might provide a webhook for new contacts but not for changes to an important subfield. A notification may contain only a reference, requiring a separate request for current state. Check the contents, conditions and treatment of deletion or status transitions for each relevant event. Where uncertain, request a working example from the intended administration rather than assuming all catalogue descriptions apply.

Establish whether processing needs the state at the event’s original time or the latest state when handling begins. Several quick changes can make those different. A reference-only event is not automatically a complete historical record. Where the source does not retain required information, adjust the scope or investigate separate capture. The integration cannot reconstruct unavailable business history merely by changing its delivery mechanism.

Receive notifications without blocking on lengthy work

A receiver needs to answer delivery according to the supplier’s contract. Performing lengthy business processing within that request can cause failure or repeated delivery. GitHub, for example, recommends prompt responses and discusses asynchronous handling; the actual response deadline is supplier-specific. One design can record receipt durably and process the contents separately, subject to validation and the agreed business rules.

Do not present acknowledged receipt as completed work. Distinguish received notifications, waiting items and confirmed destination results. Test an interruption after receipt but before execution. The item should remain recoverable. A fast success response without durable storage may lose work while the source believes delivery succeeded. This boundary deserves acceptance evidence because an ordinary successful demonstration will not reveal the difference between acknowledgement and reliable processing.

Whichever delivery method you choose, missing or failed processing needs a recovery path: An API integration has stopped: investigate and recover without duplicate work.

GitHub: Best practices for using webhooks ↗

Validate authenticity and meaning

A publicly reachable webhook endpoint can receive accidental or forged requests. Use the supplier’s supported authenticity checks and validate relevant content before processing. GitHub documents webhook secrets and HTTPS as part of its recommendations. Those are specific source examples; the actual design must also account for the chosen supplier and the environment in which your receiver operates.

Even an authentic message may have an unwanted event type or refer to the wrong administration. Check event type, intended environment and business scope. Test messages must not accidentally trigger production actions. Keep credentials out of URLs and error messages. Provide enough references for investigation without copying complete sensitive payloads into broad notification channels where every support user may be able to read them indefinitely.

GitHub: Best practices for using webhooks ↗

Design polling around the actual API

A poll may select changes after the last confirmed point. Investigate sorting, pagination and how equal timestamps are represented. A modification occurring during a read can otherwise fall outside a poorly chosen window. Advance the processing checkpoint only when the corresponding selection has been handled sufficiently and remaining work can be found safely after a restart or temporary failure.

Test multiple pages and updates at the selection boundary. A controlled overlap can help where the API supports that approach, provided repeated items use the same recognition rules as other delivery routes. An unlimited overlap without protection creates repeated work; no overlap can conceal gaps. Document the choice and the API properties supporting it instead of assuming one interval or timestamp rule works across all products.

Use common business protection for both paths

A webhook can signal a change quickly while periodic reconciliation checks later that every relevant item was handled. This can improve recovery, but both routes need the same identity and rules for previously completed operations. Two independent scripts that each create everything can cause more duplicates than one modest periodic process. A combined design should share decisions instead of merely sharing application credentials.

In a fictional trial deliberately omit a webhook. Reconciliation discovers the missing order and handles it using the normal rules. Then deliver the delayed webhook. No second draft should appear. The expected result is one identifiable business operation, with clear evidence that the other path encountered an already recognised event or instruction. This scenario tests the value of the combination more meaningfully than demonstrating two separate successful routes.

Monitor the business backlog

Do not rely only on webhook counts or the time of the last poll. A successful poll may return nothing because its selection is wrong. An active webhook receiver may see only some relevant events. Combine technical signals with reconciliation of suitable source and destination references. The comparison must match the data model and business process instead of assuming that equal raw counts mean equal outcomes.

Show which period has been reliably checked and what remains open. Assign a person to respond when that window falls behind. Can the business continue manually, and how will subsequent automation recognise actions already taken? Include that temporary procedure in the recovery plan. Otherwise a brief supplier interruption can become a longer problem when resumed processing duplicates or contradicts the work employees performed while it was unavailable.

Choose using demonstrated capabilities

Compare the candidates with the same cases: normal updates, busy periods, repeated delivery, temporary outage, expired access and a missing event. Assess delay, understandable failures and investigation effort. A design that appears immediate on paper may be more difficult to operate than a straightforward batch with a clear review procedure. Choose what meets the agreed requirement and can be explained to the team.

Record the final decision as an operating agreement: these events start processing, this is the expected freshness, this check discovers gaps and this procedure restores work. Include vendor dependencies and revisit them when the process changes. Different applications do not all require the same mechanism. They need a coherent integration whose event handling, reconciliation and ownership lead to a consistent and testable business result.

Turn the explanation into a project decision

Record your assumptions, unknowns and acceptance checks in the matching tool. Use the service guides to discuss delivery and scope.

• API integration ↗
• CRM integration ↗

Questions about this topic

Continue with a related question